@taphubhq/sdk-core 0.23.3 → 0.24.0

package/dist/index.cjs

@@ -59,7 +59,8 @@ __export(index_exports, {
   isTerminal: () => isTerminal,
   isWin: () => isWin,
   normalCDF: () => normalCDF,
-  normalPDF: () => normalPDF
+  normalPDF: () => normalPDF,
+  pairIdFromBidResultTopic: () => pairIdFromBidResultTopic
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1043,6 +1044,19 @@ function walletBalanceTopic(userId) {
 function agencyPairStatsTopic(aid, pairId) {
   return `public/agency/${aid}/pair/${pairId}/stats`;
 }
+function userBidsWildcardTopic(userId) {
+  return `${TOPIC_PREFIX}/+/user/${userId}/bid_result`;
+}
+function topicMatchesWildcard(pattern, topic) {
+  const pp = pattern.split("/");
+  const tp = topic.split("/");
+  if (pp.length !== tp.length) return false;
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i] === "+") continue;
+    if (pp[i] !== tp[i]) return false;
+  }
+  return true;
+}
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
@@ -1061,6 +1075,7 @@ function createMqttTransport(endpoint, opts = {}) {
   const candleSubscriptions = /* @__PURE__ */ new Map();
   const statsSubscriptions = /* @__PURE__ */ new Map();
   const walletSubscriptions = /* @__PURE__ */ new Map();
+  const userBidsSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle, auth } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -1111,6 +1126,9 @@ function createMqttTransport(endpoint, opts = {}) {
       for (const entry of walletSubscriptions.values()) {
         c.subscribe(entry.topic, { qos: 1 });
       }
+      for (const entry of userBidsSubscriptions.values()) {
+        c.subscribe(entry.pattern, { qos: 1 });
+      }
       fireLifecycle({ kind: "connect", rttMs: Date.now() - connectStartedAt });
     });
     client.on("reconnect", () => {
@@ -1159,6 +1177,19 @@ function createMqttTransport(endpoint, opts = {}) {
         walletSub.onMessage(receivedTopic, payload2);
         return;
       }
+      let userBidsPayload;
+      for (const sub of userBidsSubscriptions.values()) {
+        if (!topicMatchesWildcard(sub.pattern, receivedTopic)) continue;
+        if (userBidsPayload === void 0) {
+          try {
+            userBidsPayload = JSON.parse(message.toString());
+          } catch {
+            userBidsPayload = null;
+            sub.onError(new Error(`Invalid JSON on topic ${receivedTopic}`));
+          }
+        }
+        if (userBidsPayload != null) sub.onMessage(receivedTopic, userBidsPayload);
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -1246,6 +1277,19 @@ function createMqttTransport(endpoint, opts = {}) {
       if (client) client.unsubscribe(entry.topic);
       walletSubscriptions.delete(userId);
     },
+    subscribeUserBids(userId, onMessage, onError) {
+      if (userBidsSubscriptions.has(userId)) return;
+      const pattern = userBidsWildcardTopic(userId);
+      const mqttClient = ensureConnected();
+      userBidsSubscriptions.set(userId, { pattern, onMessage, onError });
+      mqttClient.subscribe(pattern, { qos: 1 });
+    },
+    unsubscribeUserBids(userId) {
+      const entry = userBidsSubscriptions.get(userId);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.pattern);
+      userBidsSubscriptions.delete(userId);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -1286,11 +1330,15 @@ function createMqttTransport(endpoint, opts = {}) {
         for (const entry of walletSubscriptions.values()) {
           client.unsubscribe(entry.topic);
         }
+        for (const entry of userBidsSubscriptions.values()) {
+          client.unsubscribe(entry.pattern);
+        }
       }
       subscriptions.clear();
       candleSubscriptions.clear();
       statsSubscriptions.clear();
       walletSubscriptions.clear();
+      userBidsSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1300,7 +1348,7 @@ function createMqttTransport(endpoint, opts = {}) {
 }
 
 // src/modules/realtime/index.ts
-var import_eventemitter33 = __toESM(require("eventemitter3"));
+var import_eventemitter34 = __toESM(require("eventemitter3"));
 
 // src/modules/realtime/GameChannel.ts
 var import_eventemitter3 = __toESM(require("eventemitter3"));
@@ -1312,9 +1360,9 @@ var GameChannel = class extends import_eventemitter3.default {
   }
 };
 
-// src/modules/realtime/WalletChannel.ts
+// src/modules/realtime/UserBidsChannel.ts
 var import_eventemitter32 = __toESM(require("eventemitter3"));
-var WalletChannel = class extends import_eventemitter32.default {
+var UserBidsChannel = class extends import_eventemitter32.default {
   userId;
   constructor(userId) {
     super();
@@ -1322,6 +1370,29 @@ var WalletChannel = class extends import_eventemitter32.default {
   }
 };
 
+// src/modules/realtime/WalletChannel.ts
+var import_eventemitter33 = __toESM(require("eventemitter3"));
+var WalletChannel = class extends import_eventemitter33.default {
+  userId;
+  constructor(userId) {
+    super();
+    this.userId = userId;
+  }
+};
+
+// src/modules/realtime/topic.ts
+var BID_RESULT_SUFFIX = "bid_result";
+function pairIdFromBidResultTopic(topic) {
+  if (!topic.endsWith(`/${BID_RESULT_SUFFIX}`)) return void 0;
+  const parts = topic.split("/");
+  if (parts.length !== 5 || parts[0] !== "game" || parts[2] !== "user") return void 0;
+  const gameId = parts[1];
+  const sep = gameId.indexOf(":");
+  if (sep < 0) return void 0;
+  const pairId = gameId.slice(sep + 1);
+  return pairId === "" ? void 0 : pairId;
+}
+
 // src/modules/realtime/index.ts
 var TOPIC_SUFFIX_CANDLE = "candle";
 var TOPIC_SUFFIX_BID_RESULT = "bid_result";
@@ -1344,7 +1415,7 @@ function mapWireCandle(raw) {
   if (c.coefMults !== void 0) result.coefMults = c.coefMults;
   return result;
 }
-function mapWireBidResult(raw) {
+function mapWireBidResult(raw, topicPairId) {
   const p = raw;
   switch (p.type) {
     case "accepted": {
@@ -1361,13 +1432,13 @@ function mapWireBidResult(raw) {
         userId: p.user_id
       };
       if (typeof p.balance === "string") data.balance = p.balance;
+      if (topicPairId !== void 0) data.pairId = topicPairId;
       return { event: "bidWon", data };
     }
     case "lost": {
-      return {
-        event: "bidLost",
-        data: { bidId: p.bidId }
-      };
+      const data = { bidId: p.bidId };
+      if (topicPairId !== void 0) data.pairId = topicPairId;
+      return { event: "bidLost", data };
     }
     default:
       console.warn(`Unknown bid_result type "${String(p.type)}"`);
@@ -1402,6 +1473,9 @@ function mapWireConfig(raw) {
 function mapWireIdealConfig(raw) {
   const p = raw;
   return {
+    // bid-260612 guard ①: carry the producer's pairId so consumers can reject cross-pair
+    // suggestions. Undefined when talking to a producer that predates the field.
+    pairId: p.pairId,
     cellSizeValue: p.cellSizeValue,
     currentPrice: p.currentPrice,
     reason: p.reason ?? "volatility_shift"
@@ -1412,7 +1486,7 @@ function mapWireToEvent(topic, payload) {
     return { event: "candle", data: mapWireCandle(payload) };
   }
   if (topic.endsWith(`/${TOPIC_SUFFIX_BID_RESULT}`)) {
-    return mapWireBidResult(payload);
+    return mapWireBidResult(payload, pairIdFromBidResultTopic(topic));
   }
   if (topic.endsWith(`/${TOPIC_SUFFIX_BALANCE_UPDATE}`)) {
     return { event: "balanceUpdate", data: mapWireBalanceUpdate(payload) };
@@ -1428,11 +1502,13 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-var RealtimeModule = class extends import_eventemitter33.default {
+var RealtimeModule = class extends import_eventemitter34.default {
   #transport;
   #entries = /* @__PURE__ */ new Map();
   #walletEntries = /* @__PURE__ */ new Map();
   // keyed by userId
+  #userBidsEntries = /* @__PURE__ */ new Map();
+  // keyed by userId
   #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
@@ -1563,6 +1639,64 @@ var RealtimeModule = class extends import_eventemitter33.default {
     entry.channel.removeAllListeners();
     this.#transport.unsubscribeWallet(cleanUserId);
   }
+  /**
+   * Subscribe to the user's bid-result stream across ALL pairs, via the wildcard
+   * topic `game/+/user/{userId}/bid_result`. Returns a `UserBidsChannel` that
+   * emits `bidWon` / `bidLost` for settlements on any pair the user holds a bid
+   * on — independent of which pair is currently displayed (mirrors
+   * `subscribeWallet`). Each emitted event carries the bid's `pairId`, parsed
+   * from the concrete result topic, so consumers can attribute and label it.
+   *
+   * Reference-counted by `userId`. The active pair's bid_result is ALSO delivered
+   * on the per-pair `subscribe` channel — that is intentional: the per-pair
+   * channel drives state + sound, this cross-pair channel drives notifications.
+   */
+  subscribeUserBids(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) {
+      throw new TaphubError("userId is required to subscribe to user bids", {
+        code: "UserIdRequired"
+      });
+    }
+    if (/[/+#]/.test(cleanUserId)) {
+      throw new TaphubError("userId must not contain MQTT topic separators (/ + #)", {
+        code: "InvalidUserId"
+      });
+    }
+    const existing = this.#userBidsEntries.get(cleanUserId);
+    if (existing) {
+      existing.refcount += 1;
+      return existing.channel;
+    }
+    const channel = new UserBidsChannel(cleanUserId);
+    const onMessage = (topic, payload) => {
+      const mapped = mapWireBidResult(payload, pairIdFromBidResultTopic(topic));
+      if (!mapped) return;
+      if (mapped.event === "bidWon") channel.emit("bidWon", mapped.data);
+      else if (mapped.event === "bidLost") channel.emit("bidLost", mapped.data);
+    };
+    const onError = (err) => {
+      channel.emit("error", err);
+    };
+    this.#userBidsEntries.set(cleanUserId, { userId: cleanUserId, channel, refcount: 1 });
+    this.#transport.subscribeUserBids(cleanUserId, onMessage, onError);
+    return channel;
+  }
+  /**
+   * Decrement the cross-pair user-bids subscription refcount for `userId`. Tears
+   * down the wildcard topic and removes the channel only at zero. No-op if absent.
+   */
+  unsubscribeUserBids(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) return;
+    const entry = this.#userBidsEntries.get(cleanUserId);
+    if (!entry) return;
+    entry.refcount -= 1;
+    if (entry.refcount > 0) return;
+    this.#userBidsEntries.delete(cleanUserId);
+    entry.channel.removeAllListeners();
+    this.#transport.unsubscribeUserBids(cleanUserId);
+  }
   /**
    * Subscribe to public market candle data for a pair, keyed by pairId
    * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
@@ -1614,6 +1748,10 @@ var RealtimeModule = class extends import_eventemitter33.default {
       entry.channel.removeAllListeners();
     }
     this.#walletEntries.clear();
+    for (const entry of this.#userBidsEntries.values()) {
+      entry.channel.removeAllListeners();
+    }
+    this.#userBidsEntries.clear();
     this.#transport.close();
   }
 };
@@ -2980,5 +3118,6 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   isTerminal,
   isWin,
   normalCDF,
-  normalPDF
+  normalPDF,
+  pairIdFromBidResultTopic
 });

package/dist/index.d.mts

@@ -694,6 +694,7 @@ type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
 type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttWalletMessageHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttUserBidsMessageHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
      * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
@@ -737,6 +738,16 @@ interface MqttTransport {
     subscribeWallet(userId: string, onMessage: MqttWalletMessageHandler, onError: MqttErrorHandler): void;
     /** Tear down the wallet subscription for a `userId`. No-op if not subscribed. */
     unsubscribeWallet(userId: string): void;
+    /**
+     * Subscribe to the user's bid-result stream across ALL pairs via the wildcard
+     * topic `game/+/user/{userId}/bid_result`. Independent of any game
+     * subscription — NOT torn down by `unsubscribeAll`, survives pair switches.
+     * Idempotent per `userId`. The handler receives the CONCRETE delivered topic
+     * (with the real gameId), so the caller can parse the pairId from it.
+     */
+    subscribeUserBids(userId: string, onMessage: MqttUserBidsMessageHandler, onError: MqttErrorHandler): void;
+    /** Tear down the cross-pair user-bids subscription for a `userId`. No-op if absent. */
+    unsubscribeUserBids(userId: string): void;
     close(): void;
 }
 
@@ -791,9 +802,19 @@ interface MqttBidWonEvent {
     payout: string;
     userId: string;
     balance?: string;
+    /**
+     * Pair the won bid belongs to, e.g. "grid-ETH-USD". Derived from the result
+     * topic (`game/{agencyId}:{pairId}/user/.../bid_result`) since the won payload
+     * carries no pair. Lets consumers attribute a result to its pair — required by
+     * the cross-pair subscription (a win for a non-active pair). Undefined only
+     * when the topic shape is unrecognised.
+     */
+    pairId?: string;
 }
 interface MqttBidLostEvent {
     bidId: string;
+    /** Pair the lost bid belongs to (see {@link MqttBidWonEvent.pairId}). */
+    pairId?: string;
 }
 interface MqttBidCancelledEvent {
     bidId: string;
@@ -838,6 +859,12 @@ interface MqttConfigEvent {
     acceptableBids: number[];
 }
 interface MqttIdealConfigEvent {
+    /**
+     * game_pairs.id (e.g. "grid-ETH-USD") the suggestion was computed for. Optional for
+     * backward compat with producers predating bid-260612; when present, a consumer drops
+     * suggestions whose pairId does not match the pair it is currently viewing (guard ①).
+     */
+    pairId?: string;
     cellSizeValue: number;
     currentPrice: number;
     reason: string;
@@ -872,6 +899,24 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
     constructor(gameId: string);
 }
 
+interface UserBidsChannelEvents {
+    bidWon: [MqttBidWonEvent];
+    bidLost: [MqttBidLostEvent];
+    error: [Error];
+}
+/**
+ * User-scoped, cross-pair bid-result channel. Emits `bidWon` / `bidLost` for the
+ * user's settlements on ANY pair, via the wildcard subscription
+ * `game/+/user/{userId}/bid_result`. Independent of which pair is currently
+ * displayed — keyed by `userId`, not `gameId`, so it survives pair switches
+ * (mirror of {@link WalletChannel}). Each emitted event carries the bid's
+ * `pairId` (parsed from the result topic) so consumers can attribute it.
+ */
+declare class UserBidsChannel extends EventEmitter<UserBidsChannelEvents> {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
 interface WalletChannelEvents {
     walletBalanceUpdate: [MqttWalletBalanceEvent];
     error: [Error];
@@ -940,6 +985,24 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
      * No-op if there is no active wallet subscription for `userId`.
      */
     unsubscribeWallet(userId: string): void;
+    /**
+     * Subscribe to the user's bid-result stream across ALL pairs, via the wildcard
+     * topic `game/+/user/{userId}/bid_result`. Returns a `UserBidsChannel` that
+     * emits `bidWon` / `bidLost` for settlements on any pair the user holds a bid
+     * on — independent of which pair is currently displayed (mirrors
+     * `subscribeWallet`). Each emitted event carries the bid's `pairId`, parsed
+     * from the concrete result topic, so consumers can attribute and label it.
+     *
+     * Reference-counted by `userId`. The active pair's bid_result is ALSO delivered
+     * on the per-pair `subscribe` channel — that is intentional: the per-pair
+     * channel drives state + sound, this cross-pair channel drives notifications.
+     */
+    subscribeUserBids(userId: string): UserBidsChannel;
+    /**
+     * Decrement the cross-pair user-bids subscription refcount for `userId`. Tears
+     * down the wildcard topic and removes the channel only at zero. No-op if absent.
+     */
+    unsubscribeUserBids(userId: string): void;
     /**
      * Subscribe to public market candle data for a pair, keyed by pairId
      * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
@@ -1169,6 +1232,20 @@ declare class TaphubSlippageError extends TaphubValidationError {
     });
 }
 
+/**
+ * Extract the slash-free pairId from a bid-result topic.
+ *
+ * Accepts the concrete topic delivered by the broker, e.g.
+ * `game/acme-corp:grid-ETH-USD/user/{uid}/bid_result` → `grid-ETH-USD`.
+ *
+ * Returns `undefined` when the topic does not match the expected shape (so the
+ * caller can fall back gracefully rather than throw). The gameId segment is the
+ * composite `{agencyId}:{pairId}`; the pairId is everything after the FIRST `:`
+ * (pairId itself is slash-free and colon-free by the bid-260602-v2 id rules, but
+ * we split on the first `:` to be safe if an agencyId ever contained one).
+ */
+declare function pairIdFromBidResultTopic(topic: string): string | undefined;
+
 declare function errorFunction(x: number): number;
 declare function normalCDF(x: number): number;
 declare function normalPDF(x: number): number;
@@ -1176,4 +1253,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 MqttAuthConfig, 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 };
+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 MqttAuthConfig, 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, UserBidsChannel, type UserBidsChannelEvents, 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, pairIdFromBidResultTopic };

package/dist/index.d.ts

@@ -694,6 +694,7 @@ type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
 type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttWalletMessageHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttUserBidsMessageHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
      * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
@@ -737,6 +738,16 @@ interface MqttTransport {
     subscribeWallet(userId: string, onMessage: MqttWalletMessageHandler, onError: MqttErrorHandler): void;
     /** Tear down the wallet subscription for a `userId`. No-op if not subscribed. */
     unsubscribeWallet(userId: string): void;
+    /**
+     * Subscribe to the user's bid-result stream across ALL pairs via the wildcard
+     * topic `game/+/user/{userId}/bid_result`. Independent of any game
+     * subscription — NOT torn down by `unsubscribeAll`, survives pair switches.
+     * Idempotent per `userId`. The handler receives the CONCRETE delivered topic
+     * (with the real gameId), so the caller can parse the pairId from it.
+     */
+    subscribeUserBids(userId: string, onMessage: MqttUserBidsMessageHandler, onError: MqttErrorHandler): void;
+    /** Tear down the cross-pair user-bids subscription for a `userId`. No-op if absent. */
+    unsubscribeUserBids(userId: string): void;
     close(): void;
 }
 
@@ -791,9 +802,19 @@ interface MqttBidWonEvent {
     payout: string;
     userId: string;
     balance?: string;
+    /**
+     * Pair the won bid belongs to, e.g. "grid-ETH-USD". Derived from the result
+     * topic (`game/{agencyId}:{pairId}/user/.../bid_result`) since the won payload
+     * carries no pair. Lets consumers attribute a result to its pair — required by
+     * the cross-pair subscription (a win for a non-active pair). Undefined only
+     * when the topic shape is unrecognised.
+     */
+    pairId?: string;
 }
 interface MqttBidLostEvent {
     bidId: string;
+    /** Pair the lost bid belongs to (see {@link MqttBidWonEvent.pairId}). */
+    pairId?: string;
 }
 interface MqttBidCancelledEvent {
     bidId: string;
@@ -838,6 +859,12 @@ interface MqttConfigEvent {
     acceptableBids: number[];
 }
 interface MqttIdealConfigEvent {
+    /**
+     * game_pairs.id (e.g. "grid-ETH-USD") the suggestion was computed for. Optional for
+     * backward compat with producers predating bid-260612; when present, a consumer drops
+     * suggestions whose pairId does not match the pair it is currently viewing (guard ①).
+     */
+    pairId?: string;
     cellSizeValue: number;
     currentPrice: number;
     reason: string;
@@ -872,6 +899,24 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
     constructor(gameId: string);
 }
 
+interface UserBidsChannelEvents {
+    bidWon: [MqttBidWonEvent];
+    bidLost: [MqttBidLostEvent];
+    error: [Error];
+}
+/**
+ * User-scoped, cross-pair bid-result channel. Emits `bidWon` / `bidLost` for the
+ * user's settlements on ANY pair, via the wildcard subscription
+ * `game/+/user/{userId}/bid_result`. Independent of which pair is currently
+ * displayed — keyed by `userId`, not `gameId`, so it survives pair switches
+ * (mirror of {@link WalletChannel}). Each emitted event carries the bid's
+ * `pairId` (parsed from the result topic) so consumers can attribute it.
+ */
+declare class UserBidsChannel extends EventEmitter<UserBidsChannelEvents> {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
 interface WalletChannelEvents {
     walletBalanceUpdate: [MqttWalletBalanceEvent];
     error: [Error];
@@ -940,6 +985,24 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
      * No-op if there is no active wallet subscription for `userId`.
      */
     unsubscribeWallet(userId: string): void;
+    /**
+     * Subscribe to the user's bid-result stream across ALL pairs, via the wildcard
+     * topic `game/+/user/{userId}/bid_result`. Returns a `UserBidsChannel` that
+     * emits `bidWon` / `bidLost` for settlements on any pair the user holds a bid
+     * on — independent of which pair is currently displayed (mirrors
+     * `subscribeWallet`). Each emitted event carries the bid's `pairId`, parsed
+     * from the concrete result topic, so consumers can attribute and label it.
+     *
+     * Reference-counted by `userId`. The active pair's bid_result is ALSO delivered
+     * on the per-pair `subscribe` channel — that is intentional: the per-pair
+     * channel drives state + sound, this cross-pair channel drives notifications.
+     */
+    subscribeUserBids(userId: string): UserBidsChannel;
+    /**
+     * Decrement the cross-pair user-bids subscription refcount for `userId`. Tears
+     * down the wildcard topic and removes the channel only at zero. No-op if absent.
+     */
+    unsubscribeUserBids(userId: string): void;
     /**
      * Subscribe to public market candle data for a pair, keyed by pairId
      * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
@@ -1169,6 +1232,20 @@ declare class TaphubSlippageError extends TaphubValidationError {
     });
 }
 
+/**
+ * Extract the slash-free pairId from a bid-result topic.
+ *
+ * Accepts the concrete topic delivered by the broker, e.g.
+ * `game/acme-corp:grid-ETH-USD/user/{uid}/bid_result` → `grid-ETH-USD`.
+ *
+ * Returns `undefined` when the topic does not match the expected shape (so the
+ * caller can fall back gracefully rather than throw). The gameId segment is the
+ * composite `{agencyId}:{pairId}`; the pairId is everything after the FIRST `:`
+ * (pairId itself is slash-free and colon-free by the bid-260602-v2 id rules, but
+ * we split on the first `:` to be safe if an agencyId ever contained one).
+ */
+declare function pairIdFromBidResultTopic(topic: string): string | undefined;
+
 declare function errorFunction(x: number): number;
 declare function normalCDF(x: number): number;
 declare function normalPDF(x: number): number;
@@ -1176,4 +1253,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 MqttAuthConfig, 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 };
+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 MqttAuthConfig, 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, UserBidsChannel, type UserBidsChannelEvents, 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, pairIdFromBidResultTopic };

package/dist/index.js

@@ -978,6 +978,19 @@ function walletBalanceTopic(userId) {
 function agencyPairStatsTopic(aid, pairId) {
   return `public/agency/${aid}/pair/${pairId}/stats`;
 }
+function userBidsWildcardTopic(userId) {
+  return `${TOPIC_PREFIX}/+/user/${userId}/bid_result`;
+}
+function topicMatchesWildcard(pattern, topic) {
+  const pp = pattern.split("/");
+  const tp = topic.split("/");
+  if (pp.length !== tp.length) return false;
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i] === "+") continue;
+    if (pp[i] !== tp[i]) return false;
+  }
+  return true;
+}
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
@@ -996,6 +1009,7 @@ function createMqttTransport(endpoint, opts = {}) {
   const candleSubscriptions = /* @__PURE__ */ new Map();
   const statsSubscriptions = /* @__PURE__ */ new Map();
   const walletSubscriptions = /* @__PURE__ */ new Map();
+  const userBidsSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle, auth } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -1046,6 +1060,9 @@ function createMqttTransport(endpoint, opts = {}) {
       for (const entry of walletSubscriptions.values()) {
         c.subscribe(entry.topic, { qos: 1 });
       }
+      for (const entry of userBidsSubscriptions.values()) {
+        c.subscribe(entry.pattern, { qos: 1 });
+      }
       fireLifecycle({ kind: "connect", rttMs: Date.now() - connectStartedAt });
     });
     client.on("reconnect", () => {
@@ -1094,6 +1111,19 @@ function createMqttTransport(endpoint, opts = {}) {
         walletSub.onMessage(receivedTopic, payload2);
         return;
       }
+      let userBidsPayload;
+      for (const sub of userBidsSubscriptions.values()) {
+        if (!topicMatchesWildcard(sub.pattern, receivedTopic)) continue;
+        if (userBidsPayload === void 0) {
+          try {
+            userBidsPayload = JSON.parse(message.toString());
+          } catch {
+            userBidsPayload = null;
+            sub.onError(new Error(`Invalid JSON on topic ${receivedTopic}`));
+          }
+        }
+        if (userBidsPayload != null) sub.onMessage(receivedTopic, userBidsPayload);
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -1181,6 +1211,19 @@ function createMqttTransport(endpoint, opts = {}) {
       if (client) client.unsubscribe(entry.topic);
       walletSubscriptions.delete(userId);
     },
+    subscribeUserBids(userId, onMessage, onError) {
+      if (userBidsSubscriptions.has(userId)) return;
+      const pattern = userBidsWildcardTopic(userId);
+      const mqttClient = ensureConnected();
+      userBidsSubscriptions.set(userId, { pattern, onMessage, onError });
+      mqttClient.subscribe(pattern, { qos: 1 });
+    },
+    unsubscribeUserBids(userId) {
+      const entry = userBidsSubscriptions.get(userId);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.pattern);
+      userBidsSubscriptions.delete(userId);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -1221,11 +1264,15 @@ function createMqttTransport(endpoint, opts = {}) {
         for (const entry of walletSubscriptions.values()) {
           client.unsubscribe(entry.topic);
         }
+        for (const entry of userBidsSubscriptions.values()) {
+          client.unsubscribe(entry.pattern);
+        }
       }
       subscriptions.clear();
       candleSubscriptions.clear();
       statsSubscriptions.clear();
       walletSubscriptions.clear();
+      userBidsSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1235,7 +1282,7 @@ function createMqttTransport(endpoint, opts = {}) {
 }
 
 // src/modules/realtime/index.ts
-import EventEmitter3 from "eventemitter3";
+import EventEmitter4 from "eventemitter3";
 
 // src/modules/realtime/GameChannel.ts
 import EventEmitter from "eventemitter3";
@@ -1247,9 +1294,9 @@ var GameChannel = class extends EventEmitter {
   }
 };
 
-// src/modules/realtime/WalletChannel.ts
+// src/modules/realtime/UserBidsChannel.ts
 import EventEmitter2 from "eventemitter3";
-var WalletChannel = class extends EventEmitter2 {
+var UserBidsChannel = class extends EventEmitter2 {
   userId;
   constructor(userId) {
     super();
@@ -1257,6 +1304,29 @@ var WalletChannel = class extends EventEmitter2 {
   }
 };
 
+// src/modules/realtime/WalletChannel.ts
+import EventEmitter3 from "eventemitter3";
+var WalletChannel = class extends EventEmitter3 {
+  userId;
+  constructor(userId) {
+    super();
+    this.userId = userId;
+  }
+};
+
+// src/modules/realtime/topic.ts
+var BID_RESULT_SUFFIX = "bid_result";
+function pairIdFromBidResultTopic(topic) {
+  if (!topic.endsWith(`/${BID_RESULT_SUFFIX}`)) return void 0;
+  const parts = topic.split("/");
+  if (parts.length !== 5 || parts[0] !== "game" || parts[2] !== "user") return void 0;
+  const gameId = parts[1];
+  const sep = gameId.indexOf(":");
+  if (sep < 0) return void 0;
+  const pairId = gameId.slice(sep + 1);
+  return pairId === "" ? void 0 : pairId;
+}
+
 // src/modules/realtime/index.ts
 var TOPIC_SUFFIX_CANDLE = "candle";
 var TOPIC_SUFFIX_BID_RESULT = "bid_result";
@@ -1279,7 +1349,7 @@ function mapWireCandle(raw) {
   if (c.coefMults !== void 0) result.coefMults = c.coefMults;
   return result;
 }
-function mapWireBidResult(raw) {
+function mapWireBidResult(raw, topicPairId) {
   const p = raw;
   switch (p.type) {
     case "accepted": {
@@ -1296,13 +1366,13 @@ function mapWireBidResult(raw) {
         userId: p.user_id
       };
       if (typeof p.balance === "string") data.balance = p.balance;
+      if (topicPairId !== void 0) data.pairId = topicPairId;
       return { event: "bidWon", data };
     }
     case "lost": {
-      return {
-        event: "bidLost",
-        data: { bidId: p.bidId }
-      };
+      const data = { bidId: p.bidId };
+      if (topicPairId !== void 0) data.pairId = topicPairId;
+      return { event: "bidLost", data };
     }
     default:
       console.warn(`Unknown bid_result type "${String(p.type)}"`);
@@ -1337,6 +1407,9 @@ function mapWireConfig(raw) {
 function mapWireIdealConfig(raw) {
   const p = raw;
   return {
+    // bid-260612 guard ①: carry the producer's pairId so consumers can reject cross-pair
+    // suggestions. Undefined when talking to a producer that predates the field.
+    pairId: p.pairId,
     cellSizeValue: p.cellSizeValue,
     currentPrice: p.currentPrice,
     reason: p.reason ?? "volatility_shift"
@@ -1347,7 +1420,7 @@ function mapWireToEvent(topic, payload) {
     return { event: "candle", data: mapWireCandle(payload) };
   }
   if (topic.endsWith(`/${TOPIC_SUFFIX_BID_RESULT}`)) {
-    return mapWireBidResult(payload);
+    return mapWireBidResult(payload, pairIdFromBidResultTopic(topic));
   }
   if (topic.endsWith(`/${TOPIC_SUFFIX_BALANCE_UPDATE}`)) {
     return { event: "balanceUpdate", data: mapWireBalanceUpdate(payload) };
@@ -1363,11 +1436,13 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-var RealtimeModule = class extends EventEmitter3 {
+var RealtimeModule = class extends EventEmitter4 {
   #transport;
   #entries = /* @__PURE__ */ new Map();
   #walletEntries = /* @__PURE__ */ new Map();
   // keyed by userId
+  #userBidsEntries = /* @__PURE__ */ new Map();
+  // keyed by userId
   #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
@@ -1498,6 +1573,64 @@ var RealtimeModule = class extends EventEmitter3 {
     entry.channel.removeAllListeners();
     this.#transport.unsubscribeWallet(cleanUserId);
   }
+  /**
+   * Subscribe to the user's bid-result stream across ALL pairs, via the wildcard
+   * topic `game/+/user/{userId}/bid_result`. Returns a `UserBidsChannel` that
+   * emits `bidWon` / `bidLost` for settlements on any pair the user holds a bid
+   * on — independent of which pair is currently displayed (mirrors
+   * `subscribeWallet`). Each emitted event carries the bid's `pairId`, parsed
+   * from the concrete result topic, so consumers can attribute and label it.
+   *
+   * Reference-counted by `userId`. The active pair's bid_result is ALSO delivered
+   * on the per-pair `subscribe` channel — that is intentional: the per-pair
+   * channel drives state + sound, this cross-pair channel drives notifications.
+   */
+  subscribeUserBids(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) {
+      throw new TaphubError("userId is required to subscribe to user bids", {
+        code: "UserIdRequired"
+      });
+    }
+    if (/[/+#]/.test(cleanUserId)) {
+      throw new TaphubError("userId must not contain MQTT topic separators (/ + #)", {
+        code: "InvalidUserId"
+      });
+    }
+    const existing = this.#userBidsEntries.get(cleanUserId);
+    if (existing) {
+      existing.refcount += 1;
+      return existing.channel;
+    }
+    const channel = new UserBidsChannel(cleanUserId);
+    const onMessage = (topic, payload) => {
+      const mapped = mapWireBidResult(payload, pairIdFromBidResultTopic(topic));
+      if (!mapped) return;
+      if (mapped.event === "bidWon") channel.emit("bidWon", mapped.data);
+      else if (mapped.event === "bidLost") channel.emit("bidLost", mapped.data);
+    };
+    const onError = (err) => {
+      channel.emit("error", err);
+    };
+    this.#userBidsEntries.set(cleanUserId, { userId: cleanUserId, channel, refcount: 1 });
+    this.#transport.subscribeUserBids(cleanUserId, onMessage, onError);
+    return channel;
+  }
+  /**
+   * Decrement the cross-pair user-bids subscription refcount for `userId`. Tears
+   * down the wildcard topic and removes the channel only at zero. No-op if absent.
+   */
+  unsubscribeUserBids(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) return;
+    const entry = this.#userBidsEntries.get(cleanUserId);
+    if (!entry) return;
+    entry.refcount -= 1;
+    if (entry.refcount > 0) return;
+    this.#userBidsEntries.delete(cleanUserId);
+    entry.channel.removeAllListeners();
+    this.#transport.unsubscribeUserBids(cleanUserId);
+  }
   /**
    * Subscribe to public market candle data for a pair, keyed by pairId
    * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
@@ -1549,6 +1682,10 @@ var RealtimeModule = class extends EventEmitter3 {
       entry.channel.removeAllListeners();
     }
     this.#walletEntries.clear();
+    for (const entry of this.#userBidsEntries.values()) {
+      entry.channel.removeAllListeners();
+    }
+    this.#userBidsEntries.clear();
     this.#transport.close();
   }
 };
@@ -2914,5 +3051,6 @@ export {
   isTerminal,
   isWin,
   normalCDF,
-  normalPDF
+  normalPDF,
+  pairIdFromBidResultTopic
 };

package/package.json

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