@0xmonaco/react 1.0.69 → 1.0.70

package/dist/coverage.d.ts

@@ -9,6 +9,19 @@ export declare const COVERED: {
     cancel_conditional_order: string;
     get_conditional_order: string;
     cancel_order: string;
+    upsert_lead_trader: string;
+    get_my_lead_trader: string;
+    list_my_followers: string;
+    list_lead_traders: string;
+    get_lead_trader: string;
+    list_lead_trader_closed_trades: string;
+    list_lead_trader_open_positions: string;
+    upsert_follow: string;
+    stop_follow: string;
+    list_my_follows: string;
+    get_follow: string;
+    list_follow_leader_positions: string;
+    preview_follow: string;
     close_position: string;
     batch_close_all_positions: string;
     create_challenge: string;

package/dist/coverage.js

@@ -9,6 +9,19 @@ export const COVERED = {
     cancel_conditional_order: "useTrade",
     get_conditional_order: "useTrade",
     cancel_order: "useTrade",
+    upsert_lead_trader: "useCopyTrading",
+    get_my_lead_trader: "useCopyTrading",
+    list_my_followers: "useCopyTrading",
+    list_lead_traders: "useCopyTrading",
+    get_lead_trader: "useCopyTrading",
+    list_lead_trader_closed_trades: "useCopyTrading",
+    list_lead_trader_open_positions: "useCopyTrading",
+    upsert_follow: "useCopyTrading",
+    stop_follow: "useCopyTrading",
+    list_my_follows: "useCopyTrading",
+    get_follow: "useCopyTrading",
+    list_follow_leader_positions: "useCopyTrading",
+    preview_follow: "useCopyTrading",
     close_position: "usePositions",
     batch_close_all_positions: "usePositions",
     create_challenge: "useAuth",

package/dist/hooks/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./useAuth";
+export * from "./useCopyEvents";
+export * from "./useCopyTrading";
 export * from "./useFees";
 export * from "./useInstruments";
 export * from "./useMarket";

package/dist/hooks/index.js

@@ -1,4 +1,6 @@
 export * from "./useAuth";
+export * from "./useCopyEvents";
+export * from "./useCopyTrading";
 export * from "./useFees";
 export * from "./useInstruments";
 export * from "./useMarket";

package/dist/hooks/useCopyEvents/index.d.ts

@@ -0,0 +1,2 @@
+export { MAX_RECENT_COPY_SKIPS, type UseCopyEventsReturn } from "./types";
+export { useCopyEvents } from "./useCopyEvents";

package/dist/hooks/useCopyEvents/index.js

@@ -0,0 +1,2 @@
+export { MAX_RECENT_COPY_SKIPS } from "./types";
+export { useCopyEvents } from "./useCopyEvents";

package/dist/hooks/useCopyEvents/types.d.ts

@@ -0,0 +1,37 @@
+import type { CopyRelationshipEventData, CopySkipEventData } from "@0xmonaco/types";
+/**
+ * Return type of {@link useCopyEvents}.
+ */
+export interface UseCopyEventsReturn {
+    /**
+     * Your follows as last reported on the `copy` channel, newest first (by
+     * `startedAt`, then `relationshipId`). A follow stopped while the socket was
+     * up keeps its entry with status `STOPPED` until the next snapshot, which
+     * carries live follows only.
+     */
+    relationships: CopyRelationshipEventData[];
+    /** The same entries keyed by `relationshipId` (the follow id). */
+    relationshipsById: Record<string, CopyRelationshipEventData>;
+    /**
+     * Leader fills your follows did not mirror, newest first, capped at
+     * {@link MAX_RECENT_COPY_SKIPS}. Only skips received while subscribed; the
+     * snapshot carries none. Read `getFollow` for a follow's persisted history.
+     */
+    recentSkips: CopySkipEventData[];
+    /**
+     * Whether a subscription to the `copy` channel is currently registered. Not
+     * a connection indicator: the client accepts subscriptions while the socket
+     * is down and sends them on the next open.
+     */
+    subscribed: boolean;
+    /**
+     * A rejected subscription request (the core helper's synchronous throw). Not
+     * a transport signal: connection loss and malformed frames never appear
+     * here.
+     */
+    error: Error | null;
+    /** Clear the current error state. */
+    clearError: () => void;
+}
+/** How many skips {@link UseCopyEventsReturn.recentSkips} keeps. */
+export declare const MAX_RECENT_COPY_SKIPS = 50;

package/dist/hooks/useCopyEvents/types.js

@@ -0,0 +1,2 @@
+/** How many skips {@link UseCopyEventsReturn.recentSkips} keeps. */
+export const MAX_RECENT_COPY_SKIPS = 50;

package/dist/hooks/useCopyEvents/useCopyEvents.d.ts

@@ -0,0 +1,20 @@
+import { type UseCopyEventsReturn } from "./types";
+/**
+ * Stream your copy trading follows over the authenticated `copy` channel.
+ * The subscription runs only while a user is signed in: it starts on login,
+ * and logout (or an account switch) clears the follows and skips.
+ *
+ * The subscribe-time snapshot seeds your live follows (`ACTIVE` or
+ * `CLOSE_ONLY`); each `copy_relationship_update` frame then carries a follow's
+ * FULL state and replaces its entry when its `version` is not older than the
+ * stored one. A later snapshot (after a reconnect) REPLACES the set
+ * wholesale, so a follow that stopped while the socket was down leaves it.
+ *
+ * `copy_skip` frames (leader fills a follow could not mirror) collect in
+ * `recentSkips`.
+ *
+ * `cumNetRealized` and `hwm` on each follow are its profit-share basis, not
+ * the copy account's balance; read the copy risk bucket (`copyRiskBucketId`)
+ * for that.
+ */
+export declare function useCopyEvents(): UseCopyEventsReturn;

package/dist/hooks/useCopyEvents/useCopyEvents.js

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { AuthenticationStatus, useMonacoContext } from "../../provider";
+import { useMonacoSDK } from "../useMonaco";
+import { MAX_RECENT_COPY_SKIPS } from "./types";
+const IDLE = { source: undefined, userId: undefined, byId: {}, skips: [], subscribed: false, error: null };
+/** Shared empties, so an out-of-scope render keeps a stable identity. */
+const NO_RELATIONSHIPS = {};
+const NO_SKIPS = [];
+/**
+ * Whether a live frame supersedes the stored row. `version` is the durable-log
+ * sequence that produced the row: an older one is a late frame and is ignored.
+ * Equal is applied (the same step, re-sent). When either side has no version
+ * the frame is applied, since there is nothing to order it by.
+ */
+function supersedes(incoming, stored) {
+    if (!stored || stored.version === undefined || incoming.version === undefined)
+        return true;
+    return incoming.version >= stored.version;
+}
+/**
+ * Newest follow first. `startedAt` is compared as a parsed instant, not as a
+ * string: the server's RFC 3339 stamps carry 0, 3 or 6 fractional digits, so
+ * `…05Z` would string-sort after `…05.500Z` although it is earlier. A stamp
+ * that does not parse falls back to plain string order against its peer. The
+ * id breaks ties with a codepoint compare, so the order never shifts with the
+ * runtime locale.
+ */
+function newestFirst(left, right) {
+    const leftAt = Date.parse(left.startedAt);
+    const rightAt = Date.parse(right.startedAt);
+    if (!Number.isNaN(leftAt) && !Number.isNaN(rightAt)) {
+        if (leftAt !== rightAt)
+            return rightAt - leftAt;
+    }
+    else if (left.startedAt !== right.startedAt) {
+        return left.startedAt > right.startedAt ? -1 : 1;
+    }
+    if (left.relationshipId === right.relationshipId)
+        return 0;
+    return left.relationshipId < right.relationshipId ? -1 : 1;
+}
+/**
+ * Stream your copy trading follows over the authenticated `copy` channel.
+ * The subscription runs only while a user is signed in: it starts on login,
+ * and logout (or an account switch) clears the follows and skips.
+ *
+ * The subscribe-time snapshot seeds your live follows (`ACTIVE` or
+ * `CLOSE_ONLY`); each `copy_relationship_update` frame then carries a follow's
+ * FULL state and replaces its entry when its `version` is not older than the
+ * stored one. A later snapshot (after a reconnect) REPLACES the set
+ * wholesale, so a follow that stopped while the socket was down leaves it.
+ *
+ * `copy_skip` frames (leader fills a follow could not mirror) collect in
+ * `recentSkips`.
+ *
+ * `cumNetRealized` and `hwm` on each follow are its profit-share basis, not
+ * the copy account's balance; read the copy risk bucket (`copyRiskBucketId`)
+ * for that.
+ */
+export function useCopyEvents() {
+    const { sdk } = useMonacoSDK();
+    const { authenticationStatus } = useMonacoContext();
+    const ws = sdk?.ws;
+    // The channel is private, and login/logout leave `sdk.ws` the same object:
+    // a subscribe sent before login is refused and never resent, and logout
+    // tears down the client's handlers. Scope the subscription to the signed-in
+    // user, derived reactively from the provider's status, so it starts on
+    // login, stops (and clears) on logout, and restarts on an account switch.
+    const userId = authenticationStatus === AuthenticationStatus.AUTHENTICATED ? sdk?.getAuthState()?.user.id : undefined;
+    const [subscription, setSubscription] = useState(IDLE);
+    const inScope = subscription.source === ws && subscription.userId === userId && userId !== undefined;
+    const clearError = useCallback(() => {
+        setSubscription((prev) => (prev.error === null ? prev : { ...prev, error: null }));
+    }, []);
+    useEffect(() => {
+        if (!ws || !userId) {
+            setSubscription(IDLE);
+            return;
+        }
+        const belongsToThisSubscription = (prev) => prev.source === ws && prev.userId === userId;
+        setSubscription({ source: ws, userId, byId: {}, skips: [], subscribed: false, error: null });
+        let unsubscribe;
+        try {
+            unsubscribe = ws.copy((event) => {
+                setSubscription((prev) => {
+                    if (!belongsToThisSubscription(prev))
+                        return prev;
+                    if (event.eventType === "copy_skip") {
+                        return { ...prev, skips: [event.data, ...prev.skips].slice(0, MAX_RECENT_COPY_SKIPS) };
+                    }
+                    const id = event.data.relationshipId;
+                    if (!supersedes(event.data, prev.byId[id]))
+                        return prev;
+                    return { ...prev, byId: { ...prev.byId, [id]: event.data } };
+                });
+            }, (items) => {
+                const byId = Object.fromEntries(items.map((item) => [item.relationshipId, item]));
+                setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, byId } : prev));
+            });
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: true } : prev));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false, error } : prev));
+        }
+        return () => {
+            unsubscribe?.();
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false } : prev));
+        };
+    }, [ws, userId]);
+    const relationshipsById = inScope ? subscription.byId : NO_RELATIONSHIPS;
+    const relationships = useMemo(() => Object.values(relationshipsById).sort(newestFirst), [relationshipsById]);
+    return {
+        relationships,
+        relationshipsById,
+        recentSkips: inScope ? subscription.skips : NO_SKIPS,
+        subscribed: inScope && subscription.subscribed,
+        error: inScope ? subscription.error : null,
+        clearError,
+    };
+}

package/dist/hooks/useCopyTrading/index.d.ts

@@ -0,0 +1,2 @@
+export type { UseCopyTradingReturn } from "./types";
+export { useCopyTrading } from "./useCopyTrading";

package/dist/hooks/useCopyTrading/index.js

@@ -0,0 +1 @@
+export { useCopyTrading } from "./useCopyTrading";

package/dist/hooks/useCopyTrading/types.d.ts

@@ -0,0 +1,6 @@
+import type { CopyTradingAPI } from "@0xmonaco/types";
+/**
+ * Return type of {@link useCopyTrading}: the copy trading client methods, each
+ * with the same signature and documentation as `sdk.copyTrading`.
+ */
+export type UseCopyTradingReturn = Pick<CopyTradingAPI, "listLeadTraders" | "getLeadTrader" | "listLeadTraderClosedTrades" | "listLeadTraderOpenPositions" | "upsertLeadTrader" | "getMyLeadTrader" | "listMyFollowers" | "upsertFollow" | "stopFollow" | "listMyFollows" | "getFollow" | "listFollowLeaderPositions" | "previewFollow">;

package/dist/hooks/useCopyTrading/useCopyTrading.d.ts

@@ -0,0 +1,22 @@
+import type { UseCopyTradingReturn } from "./types";
+/**
+ * Copy trading: the public leaderboard and lead trader profiles, your own lead
+ * trader profile and followers, and your follows.
+ *
+ * Every method delegates to `sdk.copyTrading` (see `@0xmonaco/core` for the
+ * request contract). The leaderboard, `getLeadTrader` and
+ * `listLeadTraderClosedTrades` need no session; everything else is signed and
+ * scoped to the authenticated caller. Each method throws when the SDK is not
+ * available yet.
+ *
+ * For live follow state (status changes and skipped mirrors), use
+ * {@link useCopyEvents}.
+ *
+ * @example
+ * ```tsx
+ * const { listLeadTraders, upsertFollow } = useCopyTrading();
+ * const { leaders } = await listLeadTraders({ sort: "roi", window: "30d" });
+ * await upsertFollow({ leader: "alpha_trader", allocation: "1000", slPct: "0.25" });
+ * ```
+ */
+export declare const useCopyTrading: () => UseCopyTradingReturn;

package/dist/hooks/useCopyTrading/useCopyTrading.js

@@ -0,0 +1,58 @@
+import { useCallback } from "react";
+import { useMonacoSDK } from "../useMonaco";
+/**
+ * Copy trading: the public leaderboard and lead trader profiles, your own lead
+ * trader profile and followers, and your follows.
+ *
+ * Every method delegates to `sdk.copyTrading` (see `@0xmonaco/core` for the
+ * request contract). The leaderboard, `getLeadTrader` and
+ * `listLeadTraderClosedTrades` need no session; everything else is signed and
+ * scoped to the authenticated caller. Each method throws when the SDK is not
+ * available yet.
+ *
+ * For live follow state (status changes and skipped mirrors), use
+ * {@link useCopyEvents}.
+ *
+ * @example
+ * ```tsx
+ * const { listLeadTraders, upsertFollow } = useCopyTrading();
+ * const { leaders } = await listLeadTraders({ sort: "roi", window: "30d" });
+ * await upsertFollow({ leader: "alpha_trader", allocation: "1000", slPct: "0.25" });
+ * ```
+ */
+export const useCopyTrading = () => {
+    const { sdk } = useMonacoSDK();
+    const client = useCallback(() => {
+        if (!sdk)
+            throw new Error("SDK not available");
+        return sdk.copyTrading;
+    }, [sdk]);
+    const listLeadTraders = useCallback(async (params) => await client().listLeadTraders(params), [client]);
+    const getLeadTrader = useCallback(async (handle) => await client().getLeadTrader(handle), [client]);
+    const listLeadTraderClosedTrades = useCallback(async (handle, params) => await client().listLeadTraderClosedTrades(handle, params), [client]);
+    const listLeadTraderOpenPositions = useCallback(async (handle) => await client().listLeadTraderOpenPositions(handle), [client]);
+    const upsertLeadTrader = useCallback(async (params) => await client().upsertLeadTrader(params), [client]);
+    const getMyLeadTrader = useCallback(async () => await client().getMyLeadTrader(), [client]);
+    const listMyFollowers = useCallback(async (params) => await client().listMyFollowers(params), [client]);
+    const upsertFollow = useCallback(async (params) => await client().upsertFollow(params), [client]);
+    const stopFollow = useCallback(async (followId) => await client().stopFollow(followId), [client]);
+    const listMyFollows = useCallback(async (params) => await client().listMyFollows(params), [client]);
+    const getFollow = useCallback(async (followId) => await client().getFollow(followId), [client]);
+    const previewFollow = useCallback(async (params) => await client().previewFollow(params), [client]);
+    const listFollowLeaderPositions = useCallback(async (followId) => await client().listFollowLeaderPositions(followId), [client]);
+    return {
+        listLeadTraders,
+        getLeadTrader,
+        listLeadTraderClosedTrades,
+        listLeadTraderOpenPositions,
+        upsertLeadTrader,
+        getMyLeadTrader,
+        listMyFollowers,
+        upsertFollow,
+        stopFollow,
+        listMyFollows,
+        getFollow,
+        listFollowLeaderPositions,
+        previewFollow,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/react",
-	"version": "1.0.69",
+	"version": "1.0.70",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,8 +16,8 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/core": "1.0.69",
-		"@0xmonaco/types": "1.0.69"
+		"@0xmonaco/core": "1.0.70",
+		"@0xmonaco/types": "1.0.70"
 	},
 	"devDependencies": {
 		"@types/react": "^19.2.18",