@taphubhq/sdk-core 0.13.0 → 0.14.1

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AgencyPairModule: () => AgencyPairModule,
   AuthModule: () => AuthModule,
   BidModule: () => BidModule,
   GameModule: () => GameModule,
@@ -130,6 +131,61 @@ var TaphubEventBus = class {
   }
 };
 
+// src/modules/agencyPair/normalise.ts
+function normaliseAgencyPairs(rows) {
+  if (!Array.isArray(rows)) {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return rows.map((row) => ({
+    gamePairId: row.gamePairId,
+    pair: row.pair,
+    thumb: row.thumb,
+    ordering: Number(row.ordering),
+    maxCoef: Number(row.maxCoef),
+    currentPrice: Number(row.currentPrice),
+    currentVol24h: Number(row.currentVol24h)
+  }));
+}
+
+// src/modules/agencyPair/queries.ts
+var FETCH_AGENCY_PAIRS_QUERY = `query FetchAgencyPairs($filter: AgencyPairFilter) {
+  fetchAgencyPairs(filter: $filter) {
+    gamePairId pair thumb ordering maxCoef currentPrice currentVol24h
+  }
+}`;
+
+// src/modules/agencyPair/index.ts
+var AgencyPairModule = class {
+  #graphql;
+  constructor(deps) {
+    this.#graphql = deps.graphql;
+  }
+  /**
+   * List the agency-in-context's pairs with live derived stats.
+   *
+   * The agency is resolved server-side from the `x-builder-code` header the SDK
+   * sends on every request (no JWT required — Tier 0 anon-readable). There is no
+   * argument to target another agency by design.
+   */
+  async list(args) {
+    const variables = {};
+    if (args?.filter) {
+      const filter = {};
+      if (args.filter.pair !== void 0) filter.pair = args.filter.pair;
+      if (args.filter.status !== void 0) filter.status = args.filter.status;
+      variables.filter = filter;
+    }
+    const body = await this.#graphql.request(
+      FETCH_AGENCY_PAIRS_QUERY,
+      variables,
+      args?.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseAgencyPairs(body.fetchAgencyPairs);
+  }
+};
+
 // src/modules/auth/normalise.ts
 function normaliseGoogleResponse(body) {
   return {
@@ -818,9 +874,20 @@ var LocaleModule = class {
 
 // src/transport/mqtt/index.ts
 var import_mqtt = __toESM(require("mqtt"));
-var GAME_SCOPED_SUFFIXES = ["candle", "config", "ideal_config"];
+
+// src/transport/mqtt/utils.ts
+function subKey(gameId, userId) {
+  return `${gameId}::${userId ?? ""}`;
+}
+
+// src/transport/mqtt/index.ts
+var GAME_SCOPED_SUFFIXES = ["config", "ideal_config"];
 var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
+var MARKET_TOPIC_PREFIX = "market";
+function agencyPairStatsTopic(aid, gamePairId) {
+  return `public/agency/${aid}/pair/${gamePairId}/stats`;
+}
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
@@ -833,12 +900,11 @@ function normaliseUserId(userId) {
 function userScopedTopicsFor(gameId, userId) {
   return USER_SCOPED_SUFFIXES.map((s) => topicFor(gameId, s, userId));
 }
-function subKey(gameId, userId) {
-  return `${gameId}::${userId ?? ""}`;
-}
 function createMqttTransport(endpoint, opts = {}) {
   let client = null;
   const subscriptions = /* @__PURE__ */ new Map();
+  const candleSubscriptions = /* @__PURE__ */ new Map();
+  const statsSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -885,6 +951,28 @@ function createMqttTransport(endpoint, opts = {}) {
       fireLifecycle({ kind: "error", err });
     });
     client.on("message", (receivedTopic, message) => {
+      const candleSub = [...candleSubscriptions.values()].find((s) => s.topic === receivedTopic);
+      if (candleSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          return;
+        }
+        candleSub.onCandle(receivedTopic, payload2);
+        return;
+      }
+      const statsSub = statsSubscriptions.get(receivedTopic);
+      if (statsSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          return;
+        }
+        statsSub.onStats(receivedTopic, payload2);
+        return;
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -929,9 +1017,36 @@ function createMqttTransport(endpoint, opts = {}) {
         onError
       });
       for (const t of fullTopics) {
-        mqttClient.subscribe(t, { qos: t.endsWith("candle") ? 0 : 1 });
+        mqttClient.subscribe(t, { qos: 1 });
       }
     },
+    subscribeCandle(pair, onCandle) {
+      const topic = `${MARKET_TOPIC_PREFIX}/${pair.replace(/\//g, "_")}/candle`;
+      if (candleSubscriptions.has(pair)) return;
+      const mqttClient = ensureConnected();
+      candleSubscriptions.set(pair, { topic, onCandle });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeCandle(pair) {
+      const entry = candleSubscriptions.get(pair);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      candleSubscriptions.delete(pair);
+    },
+    subscribeAgencyPairStats(aid, gamePairId, onStats) {
+      const topic = agencyPairStatsTopic(aid, gamePairId);
+      if (statsSubscriptions.has(topic)) return;
+      const mqttClient = ensureConnected();
+      statsSubscriptions.set(topic, { topic, onStats });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeAgencyPairStats(aid, gamePairId) {
+      const topic = agencyPairStatsTopic(aid, gamePairId);
+      const entry = statsSubscriptions.get(topic);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      statsSubscriptions.delete(topic);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -963,8 +1078,16 @@ function createMqttTransport(endpoint, opts = {}) {
             client.unsubscribe(t);
           }
         }
+        for (const entry of candleSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
+        for (const entry of statsSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
       }
       subscriptions.clear();
+      candleSubscriptions.clear();
+      statsSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1082,17 +1205,16 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-function subKey2(gameId, userId) {
-  return `${gameId}::${userId ?? ""}`;
-}
 var RealtimeModule = class extends import_eventemitter32.default {
   #transport;
   #entries = /* @__PURE__ */ new Map();
+  #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
     if (typeof mqttEndpointOrOptions === "string") {
       this.#transport = createMqttTransport(mqttEndpointOrOptions);
     } else {
+      this.#agencyId = mqttEndpointOrOptions.agencyId;
       this.#transport = mqttEndpointOrOptions.transport ?? createMqttTransport(mqttEndpointOrOptions.mqttEndpoint, {
         onLifecycle: mqttEndpointOrOptions.onMqttLifecycle
       });
@@ -1104,7 +1226,7 @@ var RealtimeModule = class extends import_eventemitter32.default {
   }
   subscribe(gameId, userId) {
     const cleanUserId = normaliseUserId2(userId);
-    const key = subKey2(gameId, cleanUserId);
+    const key = subKey(gameId, cleanUserId);
     const existing = this.#entries.get(key);
     if (existing) {
       existing.refcount += 1;
@@ -1160,11 +1282,49 @@ var RealtimeModule = class extends import_eventemitter32.default {
     }
     target.refcount -= 1;
     if (target.refcount > 0) return;
-    const key = subKey2(target.gameId, target.userId);
+    const key = subKey(target.gameId, target.userId);
     this.#entries.delete(key);
     target.channel.removeAllListeners();
     this.#transport.unsubscribeAll(gameId, target.userId);
   }
+  /**
+   * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+   * Independent of game/agency — candle is market-wide public data.
+   */
+  subscribeCandle(pair, onCandle) {
+    this.#transport.subscribeCandle(pair, onCandle);
+  }
+  /** Unsubscribe from candle data for a pair. */
+  unsubscribeCandle(pair) {
+    this.#transport.unsubscribeCandle(pair);
+  }
+  /**
+   * Subscribe to the live per-pair stats stream for the client's own agency.
+   * Scoped to the agency the client was constructed with — there is no argument
+   * to target another agency by design.
+   */
+  subscribeAgencyPairStats(gamePairId, handler) {
+    if (!this.#agencyId) {
+      throw new TaphubError("agencyId is required to subscribe to agency pair stats", {
+        code: "AgencyIdRequired"
+      });
+    }
+    const onStats = (_topic, raw) => {
+      const p = raw;
+      handler({
+        price: Number(p.price),
+        vol24h: Number(p.vol24h),
+        maxCoef: Number(p.maxCoef),
+        ts: Number(p.ts)
+      });
+    };
+    this.#transport.subscribeAgencyPairStats(this.#agencyId, gamePairId, onStats);
+  }
+  /** Unsubscribe from the per-pair stats stream for the client's own agency. */
+  unsubscribeAgencyPairStats(gamePairId) {
+    if (!this.#agencyId) return;
+    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, gamePairId);
+  }
   disconnect() {
     for (const entry of this.#entries.values()) {
       entry.channel.removeAllListeners();
@@ -2229,6 +2389,8 @@ var TaphubClient = class {
   bid;
   /** @readonly Leaderboard module — reassignment has no effect at runtime. */
   leaderboard;
+  /** @readonly Agency pair module — reassignment has no effect at runtime. */
+  agencyPairs;
   /** @readonly Locale module — reassignment has no effect at runtime. */
   locale;
   /** @readonly Realtime module — undefined when mqttEndpoint not configured. */
@@ -2309,9 +2471,11 @@ var TaphubClient = class {
     this.game = new GameModule({ graphql: this.#graphql });
     this.bid = new BidModule({ graphql: this.#graphql });
     this.leaderboard = new LeaderboardModule({ graphql: this.#graphql });
+    this.agencyPairs = new AgencyPairModule({ graphql: this.#graphql });
     this.locale = new LocaleModule({ graphql: this.#graphql });
     this.realtime = config.mqttEndpoint ? new RealtimeModule({
       mqttEndpoint: config.mqttEndpoint,
+      agencyId: this.agencyId,
       onMqttLifecycle: createMqttProbe(this.network)
     }) : void 0;
     attachConnectionProbe(this.network);
@@ -2345,6 +2509,12 @@ var TaphubClient = class {
       enumerable: true,
       configurable: false
     });
+    Object.defineProperty(this, "agencyPairs", {
+      value: this.agencyPairs,
+      writable: false,
+      enumerable: true,
+      configurable: false
+    });
     if (this.realtime) {
       Object.defineProperty(this, "realtime", {
         value: this.realtime,
@@ -2481,6 +2651,7 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgencyPairModule,
   AuthModule,
   BidModule,
   GameModule,

package/dist/index.d.mts

@@ -63,6 +63,49 @@ interface GraphQLTransport {
     request<T>(query: string, variables?: Record<string, unknown>, opts?: GraphQLRequestOpts): Promise<T>;
 }
 
+type AgencyPairStatus = 'active' | 'paused' | 'ended';
+interface AgencyPairFilter {
+    /** Exact match on the display pair name, e.g. "ETH/USD". */
+    pair?: string;
+    /** Exact match on the agency pair status. */
+    status?: AgencyPairStatus;
+}
+interface AgencyPairStats {
+    /** game_pairs.id slug, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
+    gamePairId: string;
+    /** Display name, e.g. "ETH/USD". */
+    pair: string;
+    /** Icon URL. */
+    thumb: string;
+    /** Lower = earlier in the displayed list. */
+    ordering: number;
+    /** config.constraints.maxCoef. */
+    maxCoef: number;
+    /** Latest candle close price; 0 when no candle exists. */
+    currentPrice: number;
+    /** Sliding 24h bid-amount sum; 0 when the worker snapshot is missing or stale. */
+    currentVol24h: number;
+}
+
+interface AgencyPairModuleDeps {
+    graphql: GraphQLTransport;
+}
+declare class AgencyPairModule {
+    #private;
+    constructor(deps: AgencyPairModuleDeps);
+    /**
+     * List the agency-in-context's pairs with live derived stats.
+     *
+     * The agency is resolved server-side from the `x-builder-code` header the SDK
+     * sends on every request (no JWT required — Tier 0 anon-readable). There is no
+     * argument to target another agency by design.
+     */
+    list(args?: {
+        filter?: AgencyPairFilter;
+        signal?: AbortSignal;
+    }): Promise<AgencyPairStats[]>;
+}
+
 interface RestRequestOpts {
     signal?: AbortSignal;
 }
@@ -433,7 +476,13 @@ interface MqttWireConfig {
     max_bid_amount: number;
     acceptable_bids: number[];
 }
-type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig;
+interface MqttWireAgencyPairStats {
+    price: number;
+    vol24h: number;
+    maxCoef: number;
+    ts: number;
+}
+type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats;
 type MqttMessageHandler = (gameId: string, topic: string, payload: MqttWirePayload) => void;
 type MqttErrorHandler = (err: Error) => void;
 type MqttLifecycleEvent = {
@@ -452,14 +501,14 @@ type MqttLifecycleEvent = {
     rttMs: number;
 };
 type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
+type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
-     * Subscribe to a game's MQTT topics keyed by the tuple `(gameId, userId)`.
-     * When `userId` is nullish (including the empty string `''`), only
-     * game-scoped topics are subscribed and the entry is stored under the
-     * anonymous slot for that gameId. Two calls with the same `(gameId, userId)`
-     * tuple are idempotent; calls with the same `gameId` but a different
-     * `userId` create an independent entry with its own user-scoped topics.
+     * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
+     * keyed by the tuple `(gameId, userId)`. Does NOT subscribe to candle —
+     * use `subscribeCandle` for public market candle data.
+     * Two calls with the same `(gameId, userId)` tuple are idempotent.
      */
     subscribe(gameId: string, userId: string | null | undefined, onMessage: MqttMessageHandler, onError: MqttErrorHandler): void;
     /**
@@ -470,6 +519,23 @@ interface MqttTransport {
      * `code='AmbiguousUnsubscribe'`.
      */
     unsubscribeAll(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+     * Independent of game/agency context — candle is market-wide public data.
+     * Idempotent: multiple calls for the same pair are deduplicated.
+     */
+    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
+    /** Tear down the candle subscription for a pair. */
+    unsubscribeCandle(pair: string): void;
+    /**
+     * Subscribe to the public per-pair stats stream for an agency, topic
+     * `public/agency/{aid}/pair/{gamePairId}/stats`. `aid` and `gamePairId` are
+     * used raw (no slash escaping) to byte-match the backend publisher.
+     * Idempotent: multiple calls for the same `(aid, gamePairId)` are deduplicated.
+     */
+    subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
+    /** Tear down the stats subscription for an `(aid, gamePairId)`. */
+    unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
     close(): void;
 }
 
@@ -542,6 +608,19 @@ interface MqttIdealConfigEvent {
     currentPrice: number;
     reason: string;
 }
+/**
+ * Live per-pair stats tick from the public stream
+ * `public/agency/{aid}/pair/{gamePairId}/stats`. The backend suppresses
+ * unchanged ticks, so a subscriber may not receive an event until price or
+ * vol24h actually moves — seed initial values from `agencyPairs.list()`.
+ */
+interface MqttAgencyPairStatsEvent {
+    price: number;
+    vol24h: number;
+    maxCoef: number;
+    /** Unix epoch **seconds** (matches the backend snapshot `ts`). */
+    ts: number;
+}
 
 interface GameChannelEvents {
     candle: [MqttCandleEvent];
@@ -561,6 +640,12 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
 
 interface RealtimeModuleOptions {
     mqttEndpoint: string;
+    /**
+     * The client's own agency id. Threaded so `subscribeAgencyPairStats` can
+     * scope the stats topic to this agency without accepting a target agency from
+     * the caller (tenant-scoping mirror of the GQL resolver).
+     */
+    agencyId?: string;
     /** @internal For testing only */
     transport?: MqttTransport;
     /**
@@ -580,6 +665,21 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
     get _transport(): MqttTransport;
     subscribe(gameId: string, userId?: string | null): GameChannel;
     unsubscribe(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+     * Independent of game/agency — candle is market-wide public data.
+     */
+    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
+    /** Unsubscribe from candle data for a pair. */
+    unsubscribeCandle(pair: string): void;
+    /**
+     * Subscribe to the live per-pair stats stream for the client's own agency.
+     * Scoped to the agency the client was constructed with — there is no argument
+     * to target another agency by design.
+     */
+    subscribeAgencyPairStats(gamePairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
+    /** Unsubscribe from the per-pair stats stream for the client's own agency. */
+    unsubscribeAgencyPairStats(gamePairId: string): void;
     disconnect(): void;
 }
 
@@ -688,6 +788,8 @@ declare class TaphubClient {
     bid: BidModule;
     /** @readonly Leaderboard module — reassignment has no effect at runtime. */
     leaderboard: LeaderboardModule;
+    /** @readonly Agency pair module — reassignment has no effect at runtime. */
+    agencyPairs: AgencyPairModule;
     /** @readonly Locale module — reassignment has no effect at runtime. */
     locale: LocaleModule;
     /** @readonly Realtime module — undefined when mqttEndpoint not configured. */
@@ -777,4 +879,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 { AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, type Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, 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 Wallet as UserWallet, type Wallet$1 as Wallet, 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, type Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 NetworkLevel, type NetworkQuality, NetworkQualityMonitor, 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 Wallet as UserWallet, type Wallet$1 as Wallet, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };

package/dist/index.d.ts

@@ -63,6 +63,49 @@ interface GraphQLTransport {
     request<T>(query: string, variables?: Record<string, unknown>, opts?: GraphQLRequestOpts): Promise<T>;
 }
 
+type AgencyPairStatus = 'active' | 'paused' | 'ended';
+interface AgencyPairFilter {
+    /** Exact match on the display pair name, e.g. "ETH/USD". */
+    pair?: string;
+    /** Exact match on the agency pair status. */
+    status?: AgencyPairStatus;
+}
+interface AgencyPairStats {
+    /** game_pairs.id slug, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
+    gamePairId: string;
+    /** Display name, e.g. "ETH/USD". */
+    pair: string;
+    /** Icon URL. */
+    thumb: string;
+    /** Lower = earlier in the displayed list. */
+    ordering: number;
+    /** config.constraints.maxCoef. */
+    maxCoef: number;
+    /** Latest candle close price; 0 when no candle exists. */
+    currentPrice: number;
+    /** Sliding 24h bid-amount sum; 0 when the worker snapshot is missing or stale. */
+    currentVol24h: number;
+}
+
+interface AgencyPairModuleDeps {
+    graphql: GraphQLTransport;
+}
+declare class AgencyPairModule {
+    #private;
+    constructor(deps: AgencyPairModuleDeps);
+    /**
+     * List the agency-in-context's pairs with live derived stats.
+     *
+     * The agency is resolved server-side from the `x-builder-code` header the SDK
+     * sends on every request (no JWT required — Tier 0 anon-readable). There is no
+     * argument to target another agency by design.
+     */
+    list(args?: {
+        filter?: AgencyPairFilter;
+        signal?: AbortSignal;
+    }): Promise<AgencyPairStats[]>;
+}
+
 interface RestRequestOpts {
     signal?: AbortSignal;
 }
@@ -433,7 +476,13 @@ interface MqttWireConfig {
     max_bid_amount: number;
     acceptable_bids: number[];
 }
-type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig;
+interface MqttWireAgencyPairStats {
+    price: number;
+    vol24h: number;
+    maxCoef: number;
+    ts: number;
+}
+type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats;
 type MqttMessageHandler = (gameId: string, topic: string, payload: MqttWirePayload) => void;
 type MqttErrorHandler = (err: Error) => void;
 type MqttLifecycleEvent = {
@@ -452,14 +501,14 @@ type MqttLifecycleEvent = {
     rttMs: number;
 };
 type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
+type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
-     * Subscribe to a game's MQTT topics keyed by the tuple `(gameId, userId)`.
-     * When `userId` is nullish (including the empty string `''`), only
-     * game-scoped topics are subscribed and the entry is stored under the
-     * anonymous slot for that gameId. Two calls with the same `(gameId, userId)`
-     * tuple are idempotent; calls with the same `gameId` but a different
-     * `userId` create an independent entry with its own user-scoped topics.
+     * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
+     * keyed by the tuple `(gameId, userId)`. Does NOT subscribe to candle —
+     * use `subscribeCandle` for public market candle data.
+     * Two calls with the same `(gameId, userId)` tuple are idempotent.
      */
     subscribe(gameId: string, userId: string | null | undefined, onMessage: MqttMessageHandler, onError: MqttErrorHandler): void;
     /**
@@ -470,6 +519,23 @@ interface MqttTransport {
      * `code='AmbiguousUnsubscribe'`.
      */
     unsubscribeAll(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+     * Independent of game/agency context — candle is market-wide public data.
+     * Idempotent: multiple calls for the same pair are deduplicated.
+     */
+    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
+    /** Tear down the candle subscription for a pair. */
+    unsubscribeCandle(pair: string): void;
+    /**
+     * Subscribe to the public per-pair stats stream for an agency, topic
+     * `public/agency/{aid}/pair/{gamePairId}/stats`. `aid` and `gamePairId` are
+     * used raw (no slash escaping) to byte-match the backend publisher.
+     * Idempotent: multiple calls for the same `(aid, gamePairId)` are deduplicated.
+     */
+    subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
+    /** Tear down the stats subscription for an `(aid, gamePairId)`. */
+    unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
     close(): void;
 }
 
@@ -542,6 +608,19 @@ interface MqttIdealConfigEvent {
     currentPrice: number;
     reason: string;
 }
+/**
+ * Live per-pair stats tick from the public stream
+ * `public/agency/{aid}/pair/{gamePairId}/stats`. The backend suppresses
+ * unchanged ticks, so a subscriber may not receive an event until price or
+ * vol24h actually moves — seed initial values from `agencyPairs.list()`.
+ */
+interface MqttAgencyPairStatsEvent {
+    price: number;
+    vol24h: number;
+    maxCoef: number;
+    /** Unix epoch **seconds** (matches the backend snapshot `ts`). */
+    ts: number;
+}
 
 interface GameChannelEvents {
     candle: [MqttCandleEvent];
@@ -561,6 +640,12 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
 
 interface RealtimeModuleOptions {
     mqttEndpoint: string;
+    /**
+     * The client's own agency id. Threaded so `subscribeAgencyPairStats` can
+     * scope the stats topic to this agency without accepting a target agency from
+     * the caller (tenant-scoping mirror of the GQL resolver).
+     */
+    agencyId?: string;
     /** @internal For testing only */
     transport?: MqttTransport;
     /**
@@ -580,6 +665,21 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
     get _transport(): MqttTransport;
     subscribe(gameId: string, userId?: string | null): GameChannel;
     unsubscribe(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+     * Independent of game/agency — candle is market-wide public data.
+     */
+    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
+    /** Unsubscribe from candle data for a pair. */
+    unsubscribeCandle(pair: string): void;
+    /**
+     * Subscribe to the live per-pair stats stream for the client's own agency.
+     * Scoped to the agency the client was constructed with — there is no argument
+     * to target another agency by design.
+     */
+    subscribeAgencyPairStats(gamePairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
+    /** Unsubscribe from the per-pair stats stream for the client's own agency. */
+    unsubscribeAgencyPairStats(gamePairId: string): void;
     disconnect(): void;
 }
 
@@ -688,6 +788,8 @@ declare class TaphubClient {
     bid: BidModule;
     /** @readonly Leaderboard module — reassignment has no effect at runtime. */
     leaderboard: LeaderboardModule;
+    /** @readonly Agency pair module — reassignment has no effect at runtime. */
+    agencyPairs: AgencyPairModule;
     /** @readonly Locale module — reassignment has no effect at runtime. */
     locale: LocaleModule;
     /** @readonly Realtime module — undefined when mqttEndpoint not configured. */
@@ -777,4 +879,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 { AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, type Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, 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 Wallet as UserWallet, type Wallet$1 as Wallet, 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, type Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 NetworkLevel, type NetworkQuality, NetworkQualityMonitor, 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 Wallet as UserWallet, type Wallet$1 as Wallet, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };

package/dist/index.js

@@ -66,6 +66,61 @@ var TaphubEventBus = class {
   }
 };
 
+// src/modules/agencyPair/normalise.ts
+function normaliseAgencyPairs(rows) {
+  if (!Array.isArray(rows)) {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return rows.map((row) => ({
+    gamePairId: row.gamePairId,
+    pair: row.pair,
+    thumb: row.thumb,
+    ordering: Number(row.ordering),
+    maxCoef: Number(row.maxCoef),
+    currentPrice: Number(row.currentPrice),
+    currentVol24h: Number(row.currentVol24h)
+  }));
+}
+
+// src/modules/agencyPair/queries.ts
+var FETCH_AGENCY_PAIRS_QUERY = `query FetchAgencyPairs($filter: AgencyPairFilter) {
+  fetchAgencyPairs(filter: $filter) {
+    gamePairId pair thumb ordering maxCoef currentPrice currentVol24h
+  }
+}`;
+
+// src/modules/agencyPair/index.ts
+var AgencyPairModule = class {
+  #graphql;
+  constructor(deps) {
+    this.#graphql = deps.graphql;
+  }
+  /**
+   * List the agency-in-context's pairs with live derived stats.
+   *
+   * The agency is resolved server-side from the `x-builder-code` header the SDK
+   * sends on every request (no JWT required — Tier 0 anon-readable). There is no
+   * argument to target another agency by design.
+   */
+  async list(args) {
+    const variables = {};
+    if (args?.filter) {
+      const filter = {};
+      if (args.filter.pair !== void 0) filter.pair = args.filter.pair;
+      if (args.filter.status !== void 0) filter.status = args.filter.status;
+      variables.filter = filter;
+    }
+    const body = await this.#graphql.request(
+      FETCH_AGENCY_PAIRS_QUERY,
+      variables,
+      args?.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseAgencyPairs(body.fetchAgencyPairs);
+  }
+};
+
 // src/modules/auth/normalise.ts
 function normaliseGoogleResponse(body) {
   return {
@@ -754,9 +809,20 @@ var LocaleModule = class {
 
 // src/transport/mqtt/index.ts
 import mqtt from "mqtt";
-var GAME_SCOPED_SUFFIXES = ["candle", "config", "ideal_config"];
+
+// src/transport/mqtt/utils.ts
+function subKey(gameId, userId) {
+  return `${gameId}::${userId ?? ""}`;
+}
+
+// src/transport/mqtt/index.ts
+var GAME_SCOPED_SUFFIXES = ["config", "ideal_config"];
 var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
+var MARKET_TOPIC_PREFIX = "market";
+function agencyPairStatsTopic(aid, gamePairId) {
+  return `public/agency/${aid}/pair/${gamePairId}/stats`;
+}
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
@@ -769,12 +835,11 @@ function normaliseUserId(userId) {
 function userScopedTopicsFor(gameId, userId) {
   return USER_SCOPED_SUFFIXES.map((s) => topicFor(gameId, s, userId));
 }
-function subKey(gameId, userId) {
-  return `${gameId}::${userId ?? ""}`;
-}
 function createMqttTransport(endpoint, opts = {}) {
   let client = null;
   const subscriptions = /* @__PURE__ */ new Map();
+  const candleSubscriptions = /* @__PURE__ */ new Map();
+  const statsSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -821,6 +886,28 @@ function createMqttTransport(endpoint, opts = {}) {
       fireLifecycle({ kind: "error", err });
     });
     client.on("message", (receivedTopic, message) => {
+      const candleSub = [...candleSubscriptions.values()].find((s) => s.topic === receivedTopic);
+      if (candleSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          return;
+        }
+        candleSub.onCandle(receivedTopic, payload2);
+        return;
+      }
+      const statsSub = statsSubscriptions.get(receivedTopic);
+      if (statsSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          return;
+        }
+        statsSub.onStats(receivedTopic, payload2);
+        return;
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -865,9 +952,36 @@ function createMqttTransport(endpoint, opts = {}) {
         onError
       });
       for (const t of fullTopics) {
-        mqttClient.subscribe(t, { qos: t.endsWith("candle") ? 0 : 1 });
+        mqttClient.subscribe(t, { qos: 1 });
       }
     },
+    subscribeCandle(pair, onCandle) {
+      const topic = `${MARKET_TOPIC_PREFIX}/${pair.replace(/\//g, "_")}/candle`;
+      if (candleSubscriptions.has(pair)) return;
+      const mqttClient = ensureConnected();
+      candleSubscriptions.set(pair, { topic, onCandle });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeCandle(pair) {
+      const entry = candleSubscriptions.get(pair);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      candleSubscriptions.delete(pair);
+    },
+    subscribeAgencyPairStats(aid, gamePairId, onStats) {
+      const topic = agencyPairStatsTopic(aid, gamePairId);
+      if (statsSubscriptions.has(topic)) return;
+      const mqttClient = ensureConnected();
+      statsSubscriptions.set(topic, { topic, onStats });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeAgencyPairStats(aid, gamePairId) {
+      const topic = agencyPairStatsTopic(aid, gamePairId);
+      const entry = statsSubscriptions.get(topic);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      statsSubscriptions.delete(topic);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -899,8 +1013,16 @@ function createMqttTransport(endpoint, opts = {}) {
             client.unsubscribe(t);
           }
         }
+        for (const entry of candleSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
+        for (const entry of statsSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
       }
       subscriptions.clear();
+      candleSubscriptions.clear();
+      statsSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1018,17 +1140,16 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-function subKey2(gameId, userId) {
-  return `${gameId}::${userId ?? ""}`;
-}
 var RealtimeModule = class extends EventEmitter2 {
   #transport;
   #entries = /* @__PURE__ */ new Map();
+  #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
     if (typeof mqttEndpointOrOptions === "string") {
       this.#transport = createMqttTransport(mqttEndpointOrOptions);
     } else {
+      this.#agencyId = mqttEndpointOrOptions.agencyId;
       this.#transport = mqttEndpointOrOptions.transport ?? createMqttTransport(mqttEndpointOrOptions.mqttEndpoint, {
         onLifecycle: mqttEndpointOrOptions.onMqttLifecycle
       });
@@ -1040,7 +1161,7 @@ var RealtimeModule = class extends EventEmitter2 {
   }
   subscribe(gameId, userId) {
     const cleanUserId = normaliseUserId2(userId);
-    const key = subKey2(gameId, cleanUserId);
+    const key = subKey(gameId, cleanUserId);
     const existing = this.#entries.get(key);
     if (existing) {
       existing.refcount += 1;
@@ -1096,11 +1217,49 @@ var RealtimeModule = class extends EventEmitter2 {
     }
     target.refcount -= 1;
     if (target.refcount > 0) return;
-    const key = subKey2(target.gameId, target.userId);
+    const key = subKey(target.gameId, target.userId);
     this.#entries.delete(key);
     target.channel.removeAllListeners();
     this.#transport.unsubscribeAll(gameId, target.userId);
   }
+  /**
+   * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
+   * Independent of game/agency — candle is market-wide public data.
+   */
+  subscribeCandle(pair, onCandle) {
+    this.#transport.subscribeCandle(pair, onCandle);
+  }
+  /** Unsubscribe from candle data for a pair. */
+  unsubscribeCandle(pair) {
+    this.#transport.unsubscribeCandle(pair);
+  }
+  /**
+   * Subscribe to the live per-pair stats stream for the client's own agency.
+   * Scoped to the agency the client was constructed with — there is no argument
+   * to target another agency by design.
+   */
+  subscribeAgencyPairStats(gamePairId, handler) {
+    if (!this.#agencyId) {
+      throw new TaphubError("agencyId is required to subscribe to agency pair stats", {
+        code: "AgencyIdRequired"
+      });
+    }
+    const onStats = (_topic, raw) => {
+      const p = raw;
+      handler({
+        price: Number(p.price),
+        vol24h: Number(p.vol24h),
+        maxCoef: Number(p.maxCoef),
+        ts: Number(p.ts)
+      });
+    };
+    this.#transport.subscribeAgencyPairStats(this.#agencyId, gamePairId, onStats);
+  }
+  /** Unsubscribe from the per-pair stats stream for the client's own agency. */
+  unsubscribeAgencyPairStats(gamePairId) {
+    if (!this.#agencyId) return;
+    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, gamePairId);
+  }
   disconnect() {
     for (const entry of this.#entries.values()) {
       entry.channel.removeAllListeners();
@@ -2165,6 +2324,8 @@ var TaphubClient = class {
   bid;
   /** @readonly Leaderboard module — reassignment has no effect at runtime. */
   leaderboard;
+  /** @readonly Agency pair module — reassignment has no effect at runtime. */
+  agencyPairs;
   /** @readonly Locale module — reassignment has no effect at runtime. */
   locale;
   /** @readonly Realtime module — undefined when mqttEndpoint not configured. */
@@ -2245,9 +2406,11 @@ var TaphubClient = class {
     this.game = new GameModule({ graphql: this.#graphql });
     this.bid = new BidModule({ graphql: this.#graphql });
     this.leaderboard = new LeaderboardModule({ graphql: this.#graphql });
+    this.agencyPairs = new AgencyPairModule({ graphql: this.#graphql });
     this.locale = new LocaleModule({ graphql: this.#graphql });
     this.realtime = config.mqttEndpoint ? new RealtimeModule({
       mqttEndpoint: config.mqttEndpoint,
+      agencyId: this.agencyId,
       onMqttLifecycle: createMqttProbe(this.network)
     }) : void 0;
     attachConnectionProbe(this.network);
@@ -2281,6 +2444,12 @@ var TaphubClient = class {
       enumerable: true,
       configurable: false
     });
+    Object.defineProperty(this, "agencyPairs", {
+      value: this.agencyPairs,
+      writable: false,
+      enumerable: true,
+      configurable: false
+    });
     if (this.realtime) {
       Object.defineProperty(this, "realtime", {
         value: this.realtime,
@@ -2416,6 +2585,7 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   return Math.max(0, Math.min(1, prob));
 }
 export {
+  AgencyPairModule,
   AuthModule,
   BidModule,
   GameModule,

package/package.json

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