@taphubhq/sdk-core 0.20.0 → 0.21.0

package/dist/index.cjs

@@ -608,6 +608,41 @@ function normaliseLeaderboard(rows) {
     gain: row.gain
   }));
 }
+function normaliseRankEntry(row) {
+  return {
+    userId: row.userId,
+    loginBy: row.loginBy,
+    username: row.username,
+    rank: row.rank,
+    pnl: row.pnl,
+    vol: row.vol,
+    payout: row.payout,
+    wins: row.wins,
+    bids: row.bids
+  };
+}
+function normaliseRankBoard(wire) {
+  if (wire == null || typeof wire !== "object") {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return {
+    period: wire.period,
+    range: { from: wire.range?.from, to: wire.range?.to },
+    sort: wire.sort,
+    sortDir: wire.sortDir,
+    total: wire.total,
+    entries: Array.isArray(wire.entries) ? wire.entries.map(normaliseRankEntry) : []
+  };
+}
+function normaliseRankMe(wire) {
+  return {
+    rank: wire.rank,
+    total: wire.total,
+    entry: wire.entry ? normaliseRankEntry(wire.entry) : null
+  };
+}
 
 // src/modules/leaderboard/queries.ts
 var LEADERBOARD_QUERY = `query Leaderboard($period: String!, $sort_by: String!) {
@@ -615,6 +650,23 @@ var LEADERBOARD_QUERY = `query Leaderboard($period: String!, $sort_by: String!)
     user_id username rank total_bids total_wins total_wagered total_payout gain
   }
 }`;
+var RANK_LEADERBOARD_V2_QUERY = `query RankLeaderboardV2($input: RankBoardInput!) {
+  rank_leaderboardV2(input: $input) {
+    period
+    range { from to }
+    sort
+    sortDir
+    total
+    entries { userId loginBy username rank pnl vol payout wins bids }
+  }
+}`;
+var RANK_ME_QUERY = `query RankMe($input: RankMeInput!) {
+  rank_me(input: $input) {
+    rank
+    total
+    entry { userId loginBy username rank pnl vol payout wins bids }
+  }
+}`;
 
 // src/modules/leaderboard/index.ts
 var LeaderboardModule = class {
@@ -622,6 +674,11 @@ var LeaderboardModule = class {
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
+  /**
+   * @deprecated Use {@link LeaderboardModule.rankBoard}. The backend
+   * `leaderboard` query is `@deprecated` in favour of `rank_leaderboardV2`
+   * (duration presets, pnl/vol sort, pagination, current-user `me`).
+   */
   async list(args) {
     const body = await this.#graphql.publicRequest(
       LEADERBOARD_QUERY,
@@ -630,6 +687,55 @@ var LeaderboardModule = class {
     );
     return normaliseLeaderboard(body.leaderboard);
   }
+  /**
+   * Fetch the public duration-scoped rank board (`rank_leaderboardV2`).
+   *
+   * Supports the fixed period presets plus `custom` (which requires an
+   * hour-aligned `range`), `pnl`/`vol` sort with an explicit direction, offset
+   * pagination, and a `total` count for "#X of N" UI. Optional args are omitted
+   * from the wire `input` when undefined so the server defaults apply
+   * (`sort = pnl`, `sortDir = desc`, `limit = 50`, `offset = 0`).
+   *
+   * bid-260606-leaderboard-split-my-rank: the board is **public and identical for
+   * every caller** — it carries no per-user data. For the signed-in caller's own
+   * row+rank, use {@link LeaderboardModule.myRank}.
+   */
+  async rankBoard(args) {
+    const input = { period: args.period };
+    if (args.range) input.range = { from: args.range.from, to: args.range.to };
+    if (args.sort) input.sort = args.sort;
+    if (args.sortDir) input.sortDir = args.sortDir;
+    if (args.limit != null || args.offset != null) {
+      input.p = { limit: args.limit, offset: args.offset };
+    }
+    const body = await this.#graphql.publicRequest(
+      RANK_LEADERBOARD_V2_QUERY,
+      { input },
+      args.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseRankBoard(body.rank_leaderboardV2);
+  }
+  /**
+   * Fetch the signed-in caller's own row + rank for the same window (`rank_me`) —
+   * the per-user companion to {@link LeaderboardModule.rankBoard}.
+   *
+   * Unlike the board, this attaches the user JWT (`request`, not `publicRequest`)
+   * so the backend resolves the caller. Returns `null` when no user is signed in
+   * (the backend returns `rank_me: null`). `MyRank.entry` is `null` when the
+   * caller has no activity in the window.
+   */
+  async myRank(args) {
+    const input = { period: args.period };
+    if (args.range) input.range = { from: args.range.from, to: args.range.to };
+    if (args.sort) input.sort = args.sort;
+    if (args.sortDir) input.sortDir = args.sortDir;
+    const body = await this.#graphql.request(
+      RANK_ME_QUERY,
+      { input },
+      args.signal ? { signal: args.signal } : void 0
+    );
+    return body.rank_me ? normaliseRankMe(body.rank_me) : null;
+  }
 };
 
 // src/modules/locale/normalise.ts

package/dist/index.d.mts

@@ -261,7 +261,15 @@ declare class BidModule {
     }): Promise<Bid[]>;
 }
 
+/**
+ * @deprecated Use {@link RankPeriod} with `client.leaderboard.rankBoard`. The
+ * v1 `leaderboard` query is `@deprecated` on the backend in favour of
+ * `rank_leaderboardV2` (duration presets + current-user rank + pnl/vol).
+ */
 type LeaderboardPeriod = 'weekly' | 'all_time';
+/**
+ * @deprecated Use {@link RankSort} with `client.leaderboard.rankBoard`.
+ */
 type LeaderboardSortBy = 'gain' | 'wagered';
 interface LeaderboardEntry {
     userId: string;
@@ -273,6 +281,48 @@ interface LeaderboardEntry {
     totalPayout: string;
     gain: string;
 }
+/** Fixed duration filters. `custom` requires an hour-aligned `range`. */
+type RankPeriod = 'today' | 'yesterday' | 'last_7d' | 'last_30d' | 'all_time' | 'custom';
+/** `pnl` = net profit (payout - vol); `vol` = wagered volume. */
+type RankSort = 'pnl' | 'vol';
+type SortDir = 'asc' | 'desc';
+interface RankEntry {
+    userId: string;
+    /** Same denormalised value as `username`; dashboard display alias. */
+    loginBy: string;
+    username: string;
+    rank: number;
+    /** Net profit = payout - vol (decimal as string). */
+    pnl: string;
+    /** Total wagered volume (decimal as string). */
+    vol: string;
+    payout: string;
+    wins: number;
+    bids: number;
+}
+interface RankBoard {
+    period: RankPeriod;
+    /** Resolved window (after hour-align) for UI display. */
+    range: {
+        from: string;
+        to: string;
+    };
+    sort: RankSort;
+    sortDir: SortDir;
+    /** All active users in the window → "#X of N". */
+    total: number;
+    entries: RankEntry[];
+}
+/**
+ * The signed-in caller's own row + rank (`rank_me`), split out of {@link RankBoard} so the
+ * board stays a pure public/cacheable read. `entry` is `null` when the caller has no activity
+ * in the window (`rank` is then 0); `total` is the ranked-pool size for "#rank of total".
+ */
+interface MyRank {
+    rank: number;
+    entry: RankEntry | null;
+    total: number;
+}
 
 interface LeaderboardModuleDeps {
     graphql: GraphQLTransport;
@@ -280,11 +330,62 @@ interface LeaderboardModuleDeps {
 declare class LeaderboardModule {
     #private;
     constructor(deps: LeaderboardModuleDeps);
+    /**
+     * @deprecated Use {@link LeaderboardModule.rankBoard}. The backend
+     * `leaderboard` query is `@deprecated` in favour of `rank_leaderboardV2`
+     * (duration presets, pnl/vol sort, pagination, current-user `me`).
+     */
     list(args: {
         period: LeaderboardPeriod;
         sortBy: LeaderboardSortBy;
         signal?: AbortSignal;
     }): Promise<LeaderboardEntry[]>;
+    /**
+     * Fetch the public duration-scoped rank board (`rank_leaderboardV2`).
+     *
+     * Supports the fixed period presets plus `custom` (which requires an
+     * hour-aligned `range`), `pnl`/`vol` sort with an explicit direction, offset
+     * pagination, and a `total` count for "#X of N" UI. Optional args are omitted
+     * from the wire `input` when undefined so the server defaults apply
+     * (`sort = pnl`, `sortDir = desc`, `limit = 50`, `offset = 0`).
+     *
+     * bid-260606-leaderboard-split-my-rank: the board is **public and identical for
+     * every caller** — it carries no per-user data. For the signed-in caller's own
+     * row+rank, use {@link LeaderboardModule.myRank}.
+     */
+    rankBoard(args: {
+        period: RankPeriod;
+        /** ISO 8601 UTC, hour-aligned. Required iff `period === 'custom'`. */
+        range?: {
+            from: string;
+            to: string;
+        };
+        sort?: RankSort;
+        sortDir?: SortDir;
+        limit?: number;
+        offset?: number;
+        signal?: AbortSignal;
+    }): Promise<RankBoard>;
+    /**
+     * Fetch the signed-in caller's own row + rank for the same window (`rank_me`) —
+     * the per-user companion to {@link LeaderboardModule.rankBoard}.
+     *
+     * Unlike the board, this attaches the user JWT (`request`, not `publicRequest`)
+     * so the backend resolves the caller. Returns `null` when no user is signed in
+     * (the backend returns `rank_me: null`). `MyRank.entry` is `null` when the
+     * caller has no activity in the window.
+     */
+    myRank(args: {
+        period: RankPeriod;
+        /** ISO 8601 UTC, hour-aligned. Required iff `period === 'custom'`. */
+        range?: {
+            from: string;
+            to: string;
+        };
+        sort?: RankSort;
+        sortDir?: SortDir;
+        signal?: AbortSignal;
+    }): Promise<MyRank | null>;
 }
 
 /**
@@ -1023,4 +1124,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };
+export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };

package/dist/index.d.ts

@@ -261,7 +261,15 @@ declare class BidModule {
     }): Promise<Bid[]>;
 }
 
+/**
+ * @deprecated Use {@link RankPeriod} with `client.leaderboard.rankBoard`. The
+ * v1 `leaderboard` query is `@deprecated` on the backend in favour of
+ * `rank_leaderboardV2` (duration presets + current-user rank + pnl/vol).
+ */
 type LeaderboardPeriod = 'weekly' | 'all_time';
+/**
+ * @deprecated Use {@link RankSort} with `client.leaderboard.rankBoard`.
+ */
 type LeaderboardSortBy = 'gain' | 'wagered';
 interface LeaderboardEntry {
     userId: string;
@@ -273,6 +281,48 @@ interface LeaderboardEntry {
     totalPayout: string;
     gain: string;
 }
+/** Fixed duration filters. `custom` requires an hour-aligned `range`. */
+type RankPeriod = 'today' | 'yesterday' | 'last_7d' | 'last_30d' | 'all_time' | 'custom';
+/** `pnl` = net profit (payout - vol); `vol` = wagered volume. */
+type RankSort = 'pnl' | 'vol';
+type SortDir = 'asc' | 'desc';
+interface RankEntry {
+    userId: string;
+    /** Same denormalised value as `username`; dashboard display alias. */
+    loginBy: string;
+    username: string;
+    rank: number;
+    /** Net profit = payout - vol (decimal as string). */
+    pnl: string;
+    /** Total wagered volume (decimal as string). */
+    vol: string;
+    payout: string;
+    wins: number;
+    bids: number;
+}
+interface RankBoard {
+    period: RankPeriod;
+    /** Resolved window (after hour-align) for UI display. */
+    range: {
+        from: string;
+        to: string;
+    };
+    sort: RankSort;
+    sortDir: SortDir;
+    /** All active users in the window → "#X of N". */
+    total: number;
+    entries: RankEntry[];
+}
+/**
+ * The signed-in caller's own row + rank (`rank_me`), split out of {@link RankBoard} so the
+ * board stays a pure public/cacheable read. `entry` is `null` when the caller has no activity
+ * in the window (`rank` is then 0); `total` is the ranked-pool size for "#rank of total".
+ */
+interface MyRank {
+    rank: number;
+    entry: RankEntry | null;
+    total: number;
+}
 
 interface LeaderboardModuleDeps {
     graphql: GraphQLTransport;
@@ -280,11 +330,62 @@ interface LeaderboardModuleDeps {
 declare class LeaderboardModule {
     #private;
     constructor(deps: LeaderboardModuleDeps);
+    /**
+     * @deprecated Use {@link LeaderboardModule.rankBoard}. The backend
+     * `leaderboard` query is `@deprecated` in favour of `rank_leaderboardV2`
+     * (duration presets, pnl/vol sort, pagination, current-user `me`).
+     */
     list(args: {
         period: LeaderboardPeriod;
         sortBy: LeaderboardSortBy;
         signal?: AbortSignal;
     }): Promise<LeaderboardEntry[]>;
+    /**
+     * Fetch the public duration-scoped rank board (`rank_leaderboardV2`).
+     *
+     * Supports the fixed period presets plus `custom` (which requires an
+     * hour-aligned `range`), `pnl`/`vol` sort with an explicit direction, offset
+     * pagination, and a `total` count for "#X of N" UI. Optional args are omitted
+     * from the wire `input` when undefined so the server defaults apply
+     * (`sort = pnl`, `sortDir = desc`, `limit = 50`, `offset = 0`).
+     *
+     * bid-260606-leaderboard-split-my-rank: the board is **public and identical for
+     * every caller** — it carries no per-user data. For the signed-in caller's own
+     * row+rank, use {@link LeaderboardModule.myRank}.
+     */
+    rankBoard(args: {
+        period: RankPeriod;
+        /** ISO 8601 UTC, hour-aligned. Required iff `period === 'custom'`. */
+        range?: {
+            from: string;
+            to: string;
+        };
+        sort?: RankSort;
+        sortDir?: SortDir;
+        limit?: number;
+        offset?: number;
+        signal?: AbortSignal;
+    }): Promise<RankBoard>;
+    /**
+     * Fetch the signed-in caller's own row + rank for the same window (`rank_me`) —
+     * the per-user companion to {@link LeaderboardModule.rankBoard}.
+     *
+     * Unlike the board, this attaches the user JWT (`request`, not `publicRequest`)
+     * so the backend resolves the caller. Returns `null` when no user is signed in
+     * (the backend returns `rank_me: null`). `MyRank.entry` is `null` when the
+     * caller has no activity in the window.
+     */
+    myRank(args: {
+        period: RankPeriod;
+        /** ISO 8601 UTC, hour-aligned. Required iff `period === 'custom'`. */
+        range?: {
+            from: string;
+            to: string;
+        };
+        sort?: RankSort;
+        sortDir?: SortDir;
+        signal?: AbortSignal;
+    }): Promise<MyRank | null>;
 }
 
 /**
@@ -1023,4 +1124,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };
+export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };

package/dist/index.js

@@ -543,6 +543,41 @@ function normaliseLeaderboard(rows) {
     gain: row.gain
   }));
 }
+function normaliseRankEntry(row) {
+  return {
+    userId: row.userId,
+    loginBy: row.loginBy,
+    username: row.username,
+    rank: row.rank,
+    pnl: row.pnl,
+    vol: row.vol,
+    payout: row.payout,
+    wins: row.wins,
+    bids: row.bids
+  };
+}
+function normaliseRankBoard(wire) {
+  if (wire == null || typeof wire !== "object") {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return {
+    period: wire.period,
+    range: { from: wire.range?.from, to: wire.range?.to },
+    sort: wire.sort,
+    sortDir: wire.sortDir,
+    total: wire.total,
+    entries: Array.isArray(wire.entries) ? wire.entries.map(normaliseRankEntry) : []
+  };
+}
+function normaliseRankMe(wire) {
+  return {
+    rank: wire.rank,
+    total: wire.total,
+    entry: wire.entry ? normaliseRankEntry(wire.entry) : null
+  };
+}
 
 // src/modules/leaderboard/queries.ts
 var LEADERBOARD_QUERY = `query Leaderboard($period: String!, $sort_by: String!) {
@@ -550,6 +585,23 @@ var LEADERBOARD_QUERY = `query Leaderboard($period: String!, $sort_by: String!)
     user_id username rank total_bids total_wins total_wagered total_payout gain
   }
 }`;
+var RANK_LEADERBOARD_V2_QUERY = `query RankLeaderboardV2($input: RankBoardInput!) {
+  rank_leaderboardV2(input: $input) {
+    period
+    range { from to }
+    sort
+    sortDir
+    total
+    entries { userId loginBy username rank pnl vol payout wins bids }
+  }
+}`;
+var RANK_ME_QUERY = `query RankMe($input: RankMeInput!) {
+  rank_me(input: $input) {
+    rank
+    total
+    entry { userId loginBy username rank pnl vol payout wins bids }
+  }
+}`;
 
 // src/modules/leaderboard/index.ts
 var LeaderboardModule = class {
@@ -557,6 +609,11 @@ var LeaderboardModule = class {
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
+  /**
+   * @deprecated Use {@link LeaderboardModule.rankBoard}. The backend
+   * `leaderboard` query is `@deprecated` in favour of `rank_leaderboardV2`
+   * (duration presets, pnl/vol sort, pagination, current-user `me`).
+   */
   async list(args) {
     const body = await this.#graphql.publicRequest(
       LEADERBOARD_QUERY,
@@ -565,6 +622,55 @@ var LeaderboardModule = class {
     );
     return normaliseLeaderboard(body.leaderboard);
   }
+  /**
+   * Fetch the public duration-scoped rank board (`rank_leaderboardV2`).
+   *
+   * Supports the fixed period presets plus `custom` (which requires an
+   * hour-aligned `range`), `pnl`/`vol` sort with an explicit direction, offset
+   * pagination, and a `total` count for "#X of N" UI. Optional args are omitted
+   * from the wire `input` when undefined so the server defaults apply
+   * (`sort = pnl`, `sortDir = desc`, `limit = 50`, `offset = 0`).
+   *
+   * bid-260606-leaderboard-split-my-rank: the board is **public and identical for
+   * every caller** — it carries no per-user data. For the signed-in caller's own
+   * row+rank, use {@link LeaderboardModule.myRank}.
+   */
+  async rankBoard(args) {
+    const input = { period: args.period };
+    if (args.range) input.range = { from: args.range.from, to: args.range.to };
+    if (args.sort) input.sort = args.sort;
+    if (args.sortDir) input.sortDir = args.sortDir;
+    if (args.limit != null || args.offset != null) {
+      input.p = { limit: args.limit, offset: args.offset };
+    }
+    const body = await this.#graphql.publicRequest(
+      RANK_LEADERBOARD_V2_QUERY,
+      { input },
+      args.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseRankBoard(body.rank_leaderboardV2);
+  }
+  /**
+   * Fetch the signed-in caller's own row + rank for the same window (`rank_me`) —
+   * the per-user companion to {@link LeaderboardModule.rankBoard}.
+   *
+   * Unlike the board, this attaches the user JWT (`request`, not `publicRequest`)
+   * so the backend resolves the caller. Returns `null` when no user is signed in
+   * (the backend returns `rank_me: null`). `MyRank.entry` is `null` when the
+   * caller has no activity in the window.
+   */
+  async myRank(args) {
+    const input = { period: args.period };
+    if (args.range) input.range = { from: args.range.from, to: args.range.to };
+    if (args.sort) input.sort = args.sort;
+    if (args.sortDir) input.sortDir = args.sortDir;
+    const body = await this.#graphql.request(
+      RANK_ME_QUERY,
+      { input },
+      args.signal ? { signal: args.signal } : void 0
+    );
+    return body.rank_me ? normaliseRankMe(body.rank_me) : null;
+  }
 };
 
 // src/modules/locale/normalise.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taphubhq/sdk-core",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Core SDK for building on the TabHub platform",
   "license": "MIT",
   "main": "./dist/index.cjs",