@taphubhq/sdk-core 0.25.6 → 0.26.0

package/dist/index.cjs

@@ -35,10 +35,14 @@ __export(index_exports, {
   BidModule: () => BidModule,
   CANDLE_EVENT: () => CANDLE_EVENT,
   DEFAULT_CHART_HISTORY_LIMIT: () => DEFAULT_CHART_HISTORY_LIMIT,
+  DEFAULT_PROBE_TTL_SECONDS: () => DEFAULT_PROBE_TTL_SECONDS,
+  DEFAULT_REGION: () => DEFAULT_REGION,
+  KNOWN_REGIONS: () => KNOWN_REGIONS,
   LeaderboardModule: () => LeaderboardModule,
   LocaleModule: () => LocaleModule,
   NetworkQualityMonitor: () => NetworkQualityMonitor,
   PairModule: () => PairModule,
+  REGION_PROBE_CACHE_KEY: () => REGION_PROBE_CACHE_KEY,
   RealtimeModule: () => RealtimeModule,
   TaphubAuthError: () => TaphubAuthError,
   TaphubClient: () => TaphubClient,
@@ -59,6 +63,7 @@ __export(index_exports, {
   computeBaseline: () => computeBaseline,
   errorFunction: () => errorFunction,
   isCancelled: () => isCancelled,
+  isKnownRegion: () => isKnownRegion,
   isLoss: () => isLoss,
   isPending: () => isPending,
   isTerminal: () => isTerminal,
@@ -67,6 +72,8 @@ __export(index_exports, {
   normalPDF: () => normalPDF,
   normaliseLang: () => normaliseLang,
   pairIdFromBidResultTopic: () => pairIdFromBidResultTopic,
+  probeNearestRegion: () => probeNearestRegion,
+  resolveRegionBaseUrl: () => resolveRegionBaseUrl,
   roundCoefToSignificantDigits: () => roundCoefToSignificantDigits
 });
 module.exports = __toCommonJS(index_exports);
@@ -224,6 +231,36 @@ var AgencyPairModule = class {
   }
 };
 
+// src/transport/graphql/wrongRegionRetry.ts
+var WRONG_REGION_CODE = "Auth_WrongRegion";
+function wrongRegionTarget(err) {
+  if (!(err instanceof TaphubError) || err.code !== WRONG_REGION_CODE) return null;
+  const details = err.details;
+  const meta = details?.errors?.[0]?.extensions?.meta;
+  const homeRegion = meta?.homeRegion;
+  return typeof homeRegion === "string" && homeRegion !== "" ? homeRegion : null;
+}
+function withWrongRegionRetry(transport, setRegion) {
+  async function retryOnce(call) {
+    try {
+      return await call();
+    } catch (err) {
+      const homeRegion = wrongRegionTarget(err);
+      if (homeRegion === null) throw err;
+      setRegion(homeRegion);
+      return await call();
+    }
+  }
+  return {
+    request(query, variables, opts) {
+      return retryOnce(() => transport.request(query, variables, opts));
+    },
+    publicRequest(query, variables, opts) {
+      return retryOnce(() => transport.publicRequest(query, variables, opts));
+    }
+  };
+}
+
 // src/modules/auth/normalise.ts
 function normaliseGoogleResponse(body) {
   return {
@@ -295,6 +332,7 @@ function normaliseUserLoginResponse(body) {
     throw new TaphubServerError("Invalid response from server", { code: "InvalidResponse" });
   }
   const wallet = node.user.defaultWallet;
+  const homeRegion = node.homeRegion ?? void 0;
   return {
     accessToken: node.accessToken,
     user: {
@@ -309,9 +347,17 @@ function normaliseUserLoginResponse(body) {
         isEnabled: wallet.isEnable
       }
     },
-    isDemo: false
+    isDemo: false,
+    homeRegion
   };
 }
+function normaliseRefreshResponse(body) {
+  const node = body.refreshTapHubToken;
+  if (!node || typeof node.accessToken !== "string" || node.accessToken === "" || typeof node.refreshToken !== "string" || node.refreshToken === "") {
+    throw new TaphubServerError("Invalid response from server", { code: "InvalidResponse" });
+  }
+  return { taphubToken: node.accessToken, refreshToken: node.refreshToken };
+}
 function validateLoginBody(body) {
   if (typeof body.access_token !== "string" || body.access_token === "") {
     throw new TaphubServerError("Invalid response from server", {
@@ -340,10 +386,21 @@ var CREATE_DEMO_USER_MUTATION = `
     }
   }
 `;
+var REFRESH_TAPHUB_TOKEN_MUTATION = `
+  mutation refreshTapHubToken($refreshToken: String!, $clientMeta: JSON) {
+    refreshTapHubToken(refreshToken: $refreshToken, clientMeta: $clientMeta) {
+      accessToken
+      refreshToken
+    }
+  }
+`;
 var USER_LOGIN_MUTATION = `
   mutation UserLogin($input: LoginInput!) {
     userLogin(input: $input) {
       accessToken
+      # multi-geo (infra-260715): home region sourced from the global region-directory
+      # (first join stores the supplied region; the stored region wins thereafter).
+      homeRegion
       user {
         id
         agencyUid
@@ -365,16 +422,32 @@ var AuthModule = class {
   #rest;
   #graphql;
   #graphqlUser;
+  #graphqlUserData;
   #setToken;
+  #isDemo;
   #agencyId;
+  #getRegion;
+  #setRegion;
   #onLoginSuccess;
   #onLogout;
+  /**
+   * Single-flight cache for {@link refreshTapHubToken}, keyed by the region the
+   * in-flight refresh was started under. Concurrent callers in the SAME region
+   * share the one network round-trip; a region change mid-flight (getRegion now
+   * differs) means the next caller starts a FRESH refresh targeting the new
+   * region rather than reusing a promise bound to the old cluster (task 2.3).
+   */
+  #refreshInflight = null;
   constructor(deps) {
     this.#rest = deps.rest;
     this.#graphql = deps.graphql;
     this.#graphqlUser = deps.graphqlUser;
+    this.#graphqlUserData = deps.graphqlUserData ?? deps.graphqlUser;
     this.#setToken = deps.setToken;
+    this.#isDemo = deps.isDemo ?? (() => false);
     this.#agencyId = deps.agencyId;
+    this.#getRegion = deps.getRegion;
+    this.#setRegion = deps.setRegion;
     this.#onLoginSuccess = deps.onLoginSuccess;
     this.#onLogout = deps.onLogout;
   }
@@ -429,14 +502,35 @@ var AuthModule = class {
     return result;
   }
   async loginWithSession(sessionToken, opts) {
-    const variables = { input: { sessionToken, agencyId: this.#agencyId } };
+    const currentRegion = opts?.region ?? this.#getRegion?.() ?? void 0;
+    try {
+      return await this.#sendLogin(sessionToken, currentRegion, opts);
+    } catch (err) {
+      const homeRegion = wrongRegionTarget(err);
+      if (homeRegion === null || !this.#setRegion) throw err;
+      this.#setRegion(homeRegion);
+      return await this.#sendLogin(sessionToken, homeRegion, opts);
+    }
+  }
+  /**
+   * Single userLogin attempt against the (region-resolved) user-service endpoint.
+   * On success it stamps the token + home region and fires onLoginSuccess. Split
+   * out so {@link loginWithSession} can re-invoke it once after an
+   * Auth_WrongRegion region switch without duplicating the post-login wiring.
+   */
+  async #sendLogin(sessionToken, region, opts) {
+    const input = { sessionToken, agencyId: this.#agencyId };
+    if (region !== void 0 && region !== null) {
+      input.region = region;
+    }
+    const variables = { input };
     const body = await this.#graphqlUser.request(
       USER_LOGIN_MUTATION,
       variables,
       opts
     );
     const result = normaliseUserLoginResponse(body);
-    this.#setToken(result.accessToken, { isDemo: false });
+    this.#setToken(result.accessToken, { isDemo: false, homeRegion: result.homeRegion });
     if (this.#onLoginSuccess) {
       try {
         await this.#onLoginSuccess();
@@ -445,6 +539,60 @@ var AuthModule = class {
     }
     return result;
   }
+  /**
+   * Exchange a refresh token for a rotated (taphubToken, refreshToken) pair via
+   * the user-service (region-routed through `graphqlUserData`, so a user pinned
+   * to a non-default region refreshes against THEIR cluster — the bug this change
+   * fixes). On success the SDK's own token is updated and the rotated pair is
+   * returned so the caller can persist it (rotation contract: present the NEW
+   * refresh token next time).
+   *
+   * - **Demo-skips-refresh:** demo users have no refresh path and reject with
+   *   `Refresh_DemoNotSupported` (no network call). The caller reacts by clearing
+   *   auth / re-creating the demo user.
+   * - **Single-flight:** concurrent callers share one in-flight request, keyed by
+   *   the current region. A region change mid-flight re-targets the next caller.
+   * - **Wrong-region backstop:** `graphqlUserData` retries once on
+   *   `Auth_WrongRegion`, so a stale region self-corrects.
+   *
+   * Invalid/expired/reused refresh tokens surface as the transport's typed error
+   * (e.g. `ErrRefreshTokenInvalid`); network failures surface as
+   * `TaphubNetworkError`. The caller decides how to react (clear vs retry-later).
+   */
+  refreshTapHubToken(refreshToken, opts) {
+    if (this.#isDemo()) {
+      return Promise.reject(
+        new TaphubValidationError("demo users have no refresh path", {
+          code: "Refresh_DemoNotSupported"
+        })
+      );
+    }
+    const region = this.#getRegion?.() ?? null;
+    if (this.#refreshInflight && this.#refreshInflight.region === region) {
+      return this.#refreshInflight.promise;
+    }
+    const promise = this.#doRefresh(refreshToken, opts).finally(() => {
+      if (this.#refreshInflight?.promise === promise) {
+        this.#refreshInflight = null;
+      }
+    });
+    this.#refreshInflight = { region, promise };
+    return promise;
+  }
+  async #doRefresh(refreshToken, opts) {
+    const variables = { refreshToken };
+    if (opts?.clientMeta !== void 0) {
+      variables.clientMeta = opts.clientMeta;
+    }
+    const body = await this.#graphqlUserData.request(
+      REFRESH_TAPHUB_TOKEN_MUTATION,
+      variables,
+      opts?.signal ? { signal: opts.signal } : void 0
+    );
+    const result = normaliseRefreshResponse(body);
+    this.#setToken(result.taphubToken, { isDemo: false });
+    return result;
+  }
   async logout() {
     this.#setToken(null);
     if (this.#onLogout) {
@@ -1109,18 +1257,30 @@ function normaliseCandles(list) {
     coefMults: c.coefMults
   }));
 }
+function isAgencyComposite(id) {
+  return id.includes(":");
+}
+function stripAgencyPrefix(id) {
+  return id.slice(id.indexOf(":") + 1);
+}
 function normalisePairInfo(node) {
   if (typeof node.id !== "string" || node.id === "" || typeof node.pair !== "string" || node.pair === "") {
     throw new TaphubServerError("Invalid response from server", { code: "InvalidResponse" });
   }
+  const composite = isAgencyComposite(node.id);
   return {
-    id: node.id,
+    id: composite ? stripAgencyPrefix(node.id) : node.id,
     pair: node.pair,
-    gameplayId: node.gameplayId,
-    gameplayName: node.gameplayName,
+    // available-pairs-retired-fields: the server no longer sends these; default
+    // rather than emit `undefined` through a non-optional entity property.
+    gameplayId: node.gameplayId ?? "",
+    gameplayName: node.gameplayName ?? "",
     source: node.source,
     // REVIEW[bid-260602]: maps node.agencyPairId (was: node.gameId)
-    agencyPairId: node.agencyPairId ?? null
+    // Fall back to the wire `id` only when it IS the composite — otherwise stay
+    // null, as the retired field did, so nobody builds an MQTT topic out of a
+    // catalog id.
+    agencyPairId: node.agencyPairId ?? (composite ? node.id : null)
   };
 }
 
@@ -1146,10 +1306,7 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
   builderAvailableGamePairs(gameplayId: $gameplayId) {
     id
     pair
-    gameplayId
-    gameplayName
     source
-    agencyPairId
   }
 }`;
 
@@ -1194,8 +1351,11 @@ var PairModule = class {
   /**
    * Returns available game pairs, optionally filtered by gameplay.
    *
-   * When called with a valid JWT (authenticated builder), each entry includes
-   * `gameId` — use it directly as the MQTT topic `game/{gameId}/candle`.
+   * Each entry's `id` is the bare catalog pair id, safe to pass straight back
+   * as a `pairId` argument. When called with a valid JWT (authenticated
+   * builder), `agencyPairId` additionally carries the agency composite — use
+   * THAT one as the MQTT topic `game/{gameId}/candle`. It is `null` for
+   * anonymous callers.
    *
    * @example
    * const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' });
@@ -1245,6 +1405,9 @@ function walletBalanceTopic(userId) {
 function agencyPairStatsTopic(aid, pairId) {
   return `public/agency/${aid}/pair/${pairId}/stats`;
 }
+function userMigrationTopic(userId) {
+  return `user/${userId}/migration`;
+}
 function userBidsWildcardTopic(userId) {
   return `${TOPIC_PREFIX}/+/user/${userId}/bid_result`;
 }
@@ -1271,12 +1434,14 @@ function userScopedTopicsFor(gameId, userId) {
   return USER_SCOPED_SUFFIXES.map((s) => topicFor(gameId, s, userId));
 }
 function createMqttTransport(endpoint, opts = {}) {
+  const resolveEndpoint = () => typeof endpoint === "function" ? endpoint() : endpoint;
   let client = null;
   const subscriptions = /* @__PURE__ */ new Map();
   const candleSubscriptions = /* @__PURE__ */ new Map();
   const statsSubscriptions = /* @__PURE__ */ new Map();
   const walletSubscriptions = /* @__PURE__ */ new Map();
   const userBidsSubscriptions = /* @__PURE__ */ new Map();
+  const migrationSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle, auth } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -1289,7 +1454,7 @@ function createMqttTransport(endpoint, opts = {}) {
   function ensureConnected() {
     if (client) return client;
     connectStartedAt = Date.now();
-    client = import_mqtt.default.connect(endpoint, {
+    client = import_mqtt.default.connect(resolveEndpoint(), {
       clean: true,
       reconnectPeriod: 2e3,
       connectTimeout: 1e4,
@@ -1330,6 +1495,9 @@ function createMqttTransport(endpoint, opts = {}) {
       for (const entry of userBidsSubscriptions.values()) {
         c.subscribe(entry.pattern, { qos: 1 });
       }
+      for (const entry of migrationSubscriptions.values()) {
+        c.subscribe(entry.topic, { qos: 1 });
+      }
       fireLifecycle({ kind: "connect", rttMs: Date.now() - connectStartedAt });
     });
     client.on("reconnect", () => {
@@ -1378,6 +1546,20 @@ function createMqttTransport(endpoint, opts = {}) {
         walletSub.onMessage(receivedTopic, payload2);
         return;
       }
+      const migrationSub = [...migrationSubscriptions.values()].find(
+        (s) => s.topic === receivedTopic
+      );
+      if (migrationSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          migrationSub.onError(new Error(`Invalid JSON on topic ${receivedTopic}`));
+          return;
+        }
+        migrationSub.onMessage(receivedTopic, payload2);
+        return;
+      }
       let userBidsPayload;
       for (const sub of userBidsSubscriptions.values()) {
         if (!topicMatchesWildcard(sub.pattern, receivedTopic)) continue;
@@ -1491,6 +1673,19 @@ function createMqttTransport(endpoint, opts = {}) {
       if (client) client.unsubscribe(entry.pattern);
       userBidsSubscriptions.delete(userId);
     },
+    subscribeMigration(userId, onMessage, onError) {
+      if (migrationSubscriptions.has(userId)) return;
+      const topic = userMigrationTopic(userId);
+      const mqttClient = ensureConnected();
+      migrationSubscriptions.set(userId, { topic, onMessage, onError });
+      mqttClient.subscribe(topic, { qos: 1 });
+    },
+    unsubscribeMigration(userId) {
+      const entry = migrationSubscriptions.get(userId);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      migrationSubscriptions.delete(userId);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -1515,6 +1710,12 @@ function createMqttTransport(endpoint, opts = {}) {
       }
       subscriptions.delete(subKey(target.gameId, target.userId));
     },
+    reconnect() {
+      if (!client) return;
+      client.end(true);
+      client = null;
+      ensureConnected();
+    },
     close() {
       if (client) {
         for (const sub of subscriptions.values()) {
@@ -1534,12 +1735,16 @@ function createMqttTransport(endpoint, opts = {}) {
         for (const entry of userBidsSubscriptions.values()) {
           client.unsubscribe(entry.pattern);
         }
+        for (const entry of migrationSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
       }
       subscriptions.clear();
       candleSubscriptions.clear();
       statsSubscriptions.clear();
       walletSubscriptions.clear();
       userBidsSubscriptions.clear();
+      migrationSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1549,7 +1754,7 @@ function createMqttTransport(endpoint, opts = {}) {
 }
 
 // src/modules/realtime/index.ts
-var import_eventemitter34 = __toESM(require("eventemitter3"));
+var import_eventemitter35 = __toESM(require("eventemitter3"));
 
 // src/modules/realtime/GameChannel.ts
 var import_eventemitter3 = __toESM(require("eventemitter3"));
@@ -1561,9 +1766,9 @@ var GameChannel = class extends import_eventemitter3.default {
   }
 };
 
-// src/modules/realtime/UserBidsChannel.ts
+// src/modules/realtime/MigrationChannel.ts
 var import_eventemitter32 = __toESM(require("eventemitter3"));
-var UserBidsChannel = class extends import_eventemitter32.default {
+var MigrationChannel = class extends import_eventemitter32.default {
   userId;
   constructor(userId) {
     super();
@@ -1571,9 +1776,19 @@ var UserBidsChannel = class extends import_eventemitter32.default {
   }
 };
 
-// src/modules/realtime/WalletChannel.ts
+// src/modules/realtime/UserBidsChannel.ts
 var import_eventemitter33 = __toESM(require("eventemitter3"));
-var WalletChannel = class extends import_eventemitter33.default {
+var UserBidsChannel = class extends import_eventemitter33.default {
+  userId;
+  constructor(userId) {
+    super();
+    this.userId = userId;
+  }
+};
+
+// src/modules/realtime/WalletChannel.ts
+var import_eventemitter34 = __toESM(require("eventemitter3"));
+var WalletChannel = class extends import_eventemitter34.default {
   userId;
   constructor(userId) {
     super();
@@ -1664,6 +1879,19 @@ function mapWireWalletBalance(raw) {
     reason: p.reason ?? ""
   };
 }
+function mapWireMigrationCompleted(raw) {
+  if (raw === null || typeof raw !== "object") return null;
+  const p = raw;
+  if (p.type !== "migration_completed") return null;
+  if (typeof p.toRegion !== "string" || p.toRegion === "") return null;
+  return {
+    type: "migration_completed",
+    migrationId: p.migrationId,
+    fromRegion: p.fromRegion,
+    toRegion: p.toRegion,
+    completedAt: p.completedAt
+  };
+}
 function mapWireConfig(raw) {
   const p = raw;
   return {
@@ -1704,13 +1932,15 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-var RealtimeModule = class extends import_eventemitter34.default {
+var RealtimeModule = class extends import_eventemitter35.default {
   #transport;
   #entries = /* @__PURE__ */ new Map();
   #walletEntries = /* @__PURE__ */ new Map();
   // keyed by userId
   #userBidsEntries = /* @__PURE__ */ new Map();
   // keyed by userId
+  #migrationEntries = /* @__PURE__ */ new Map();
+  // keyed by userId
   #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
@@ -1899,6 +2129,57 @@ var RealtimeModule = class extends import_eventemitter34.default {
     entry.channel.removeAllListeners();
     this.#transport.unsubscribeUserBids(cleanUserId);
   }
+  /**
+   * Subscribe to the user-scoped migration completion stream for `userId`,
+   * topic `user/{userId}/migration` (ux-260730). Returns a `MigrationChannel`
+   * that emits `migrationCompleted` when the user's home-region migration
+   * finishes. Malformed or schema-mismatched payloads are dropped silently.
+   *
+   * Reference-counted by `userId`, mirroring `subscribeWallet`. Intended
+   * lifecycle (design D7): hold the channel only while the client is in the
+   * migrating state; unsubscribe on completion/logout. The publisher retains
+   * the completion message, so subscribing after the fact still delivers it.
+   */
+  subscribeMigration(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) {
+      throw new TaphubError("userId is required to subscribe to migration events", {
+        code: "UserIdRequired"
+      });
+    }
+    const existing = this.#migrationEntries.get(cleanUserId);
+    if (existing) {
+      existing.refcount += 1;
+      return existing.channel;
+    }
+    const channel = new MigrationChannel(cleanUserId);
+    const onMessage = (_topic, payload) => {
+      const mapped = mapWireMigrationCompleted(payload);
+      if (!mapped) return;
+      channel.emit("migrationCompleted", mapped);
+    };
+    const onError = (err) => {
+      channel.emit("error", err);
+    };
+    this.#migrationEntries.set(cleanUserId, { userId: cleanUserId, channel, refcount: 1 });
+    this.#transport.subscribeMigration(cleanUserId, onMessage, onError);
+    return channel;
+  }
+  /**
+   * Decrement the migration subscription refcount for `userId`. Tears down the
+   * MQTT topic and removes the channel only at zero. No-op if absent.
+   */
+  unsubscribeMigration(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) return;
+    const entry = this.#migrationEntries.get(cleanUserId);
+    if (!entry) return;
+    entry.refcount -= 1;
+    if (entry.refcount > 0) return;
+    this.#migrationEntries.delete(cleanUserId);
+    entry.channel.removeAllListeners();
+    this.#transport.unsubscribeMigration(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 —
@@ -1941,6 +2222,15 @@ var RealtimeModule = class extends import_eventemitter34.default {
     if (!this.#agencyId) return;
     this.#transport.unsubscribeAgencyPairStats(this.#agencyId, pairId);
   }
+  /**
+   * Reconnect the MQTT transport, re-resolving its (possibly region-scoped)
+   * endpoint. All active subscriptions are preserved and re-declared on the new
+   * connection (multi-geo home-region switch). No-op when not currently
+   * connected. Delegates to the transport's `reconnect`.
+   */
+  reconnect() {
+    this.#transport.reconnect();
+  }
   disconnect() {
     for (const entry of this.#entries.values()) {
       entry.channel.removeAllListeners();
@@ -1954,6 +2244,10 @@ var RealtimeModule = class extends import_eventemitter34.default {
       entry.channel.removeAllListeners();
     }
     this.#userBidsEntries.clear();
+    for (const entry of this.#migrationEntries.values()) {
+      entry.channel.removeAllListeners();
+    }
+    this.#migrationEntries.clear();
     this.#transport.close();
   }
 };
@@ -2046,6 +2340,9 @@ var LIST_ENABLED_CURRENCIES_QUERY = `query ListEnabledCurrencies($input: ListEna
   listEnabledCurrencies(input: $input) { code unit unitSymbol }
 }`;
 var MY_WALLET_BY_CURRENCY_QUERY = "query MyWalletByCurrency($currency: String!) { myWalletByCurrency(currency: $currency) { id amount currency isEnable } }";
+var REQUEST_REGION_MIGRATION_MUTATION = `mutation RequestRegionMigration($input: RequestRegionMigrationInput!) {
+  requestRegionMigration(input: $input) { migrationId }
+}`;
 var USER_PNL_QUERY = `query UserPnL($period: String) {
   userPnL(period: $period) {
     gain total_wagered total_payout total_bids total_wins pnlRank volRank
@@ -2095,6 +2392,29 @@ var UserModule = class {
     );
     return normaliseMyWalletByCurrencyResponse(body);
   }
+  /**
+   * Start migrating the authenticated user's home region (multi-geo Phase 2).
+   * User-service validates the JWT, checks the feature flag, and forwards to the
+   * region directory (cooldown / single-flight / region-set validation happen
+   * server-side). Typed rejections keep their `extensions.code`
+   * (Migration_Unavailable, Migration_CooldownActive, …) on the error's `code`
+   * so hosts can localise them.
+   */
+  async requestRegionMigration(toRegion, opts) {
+    const body = await this.#graphqlUser.request(
+      REQUEST_REGION_MIGRATION_MUTATION,
+      { input: { toRegion } },
+      opts
+    );
+    const migrationId = body?.requestRegionMigration?.migrationId;
+    if (typeof migrationId !== "string" || migrationId === "") {
+      throw new TaphubServerError("Invalid response from server", {
+        code: "INVALID_RESPONSE",
+        details: body
+      });
+    }
+    return { migrationId };
+  }
   get currencies() {
     return this.#currencies;
   }
@@ -2545,6 +2865,21 @@ function createRestProbe(monitor) {
   };
 }
 
+// src/region.ts
+var KNOWN_REGIONS = ["sg", "eu", "jp"];
+var DEFAULT_REGION = "sg";
+function isKnownRegion(region) {
+  return region != null && KNOWN_REGIONS.includes(region);
+}
+function resolveRegionBaseUrl(region, domains, fallbackBaseUrl) {
+  if (region == null || region === "") {
+    return fallbackBaseUrl;
+  }
+  const map = domains ?? {};
+  const effectiveRegion = isKnownRegion(region) ? region : DEFAULT_REGION;
+  return map[effectiveRegion] ?? map[DEFAULT_REGION] ?? fallbackBaseUrl;
+}
+
 // src/storage/index.ts
 var MemoryAdapter = class {
   store = /* @__PURE__ */ new Map();
@@ -2601,6 +2936,11 @@ var TaphubStorage = {
   }
 };
 
+// src/transport/shared/baseUrl.ts
+function resolveBaseUrl(input) {
+  return typeof input === "function" ? input() : input;
+}
+
 // src/transport/shared/errors.ts
 function mapNetworkErrorToTaphubError(err) {
   if (err instanceof DOMException && err.name === "AbortError") {
@@ -2756,7 +3096,7 @@ function createGraphQLTransport(deps) {
   }
   async function execute(token, query, variables, opts) {
     const fetchImpl = resolveFetch();
-    const base = baseUrl.replace(/\/+$/, "");
+    const base = resolveBaseUrl(baseUrl).replace(/\/+$/, "");
     const op = extractOp(query);
     const url = `${base}?${op}`;
     const headers = buildHeaders({ token, hasBody: true, agencyId });
@@ -2900,7 +3240,7 @@ function createRestTransport(deps) {
   }
   async function request(method, path, body, opts) {
     const fetchImpl = resolveFetch();
-    const url = buildUrl(baseUrl, path);
+    const url = buildUrl(resolveBaseUrl(baseUrl), path);
     const token = getToken();
     const hasBody = body !== void 0;
     const headers = buildHeaders({ token, hasBody });
@@ -2970,6 +3310,9 @@ function tokenStorageKey(agencyId) {
 function isDemoStorageKey(agencyId) {
   return `taphub:${agencyId}:isDemo`;
 }
+function regionStorageKey(agencyId) {
+  return `taphub:${agencyId}:region`;
+}
 var TaphubClient = class {
   agencyId;
   endpoint;
@@ -2996,11 +3339,29 @@ var TaphubClient = class {
   bus;
   #token;
   #isDemo;
+  /** User's home region (multi-geo, design D4). null → default base URL. */
+  #region;
   #tokenKey;
   #isDemoKey;
+  #regionKey;
+  /** Region → base URL map (config, never hardcoded). undefined → always use `endpoint`. */
+  #regionDomains;
+  /** Fixed MQTT broker endpoint (fallback for region resolution). undefined → no realtime. */
+  #mqttEndpoint;
+  /** Region → MQTT endpoint map (config, never hardcoded). undefined → always use `#mqttEndpoint`. */
+  #regionMqttEndpoints;
   #rest;
   #graphql;
   #graphqlUser;
+  /**
+   * Auth_WrongRegion-retrying variants of the two GraphQL transports, used by the
+   * user-scoped DATA modules (user / bid) and token refresh. A data call that
+   * lands on the wrong cluster switches the region and retries once (multi-geo
+   * backstop). Login keeps the raw transports — it runs its own wrong-region
+   * retry, so wrapping there would double-retry.
+   */
+  #graphqlData;
+  #graphqlUserData;
   constructor(config) {
     if (!config.agencyId) {
       throw new TaphubValidationError("agencyId is required", {
@@ -3025,39 +3386,62 @@ var TaphubClient = class {
     const restProbe = createRestProbe(this.network);
     this.#tokenKey = tokenStorageKey(this.agencyId);
     this.#isDemoKey = isDemoStorageKey(this.agencyId);
+    this.#regionKey = regionStorageKey(this.agencyId);
+    this.#regionDomains = config.regionDomains;
+    this.#mqttEndpoint = config.mqttEndpoint;
+    this.#regionMqttEndpoints = config.regionMqttEndpoints;
     this.#token = this.storage.get(this.#tokenKey);
     this.#isDemo = this.storage.get(this.#isDemoKey) === "1";
+    this.#region = this.storage.get(this.#regionKey);
     this.#rest = createRestTransport({
-      baseUrl: this.endpoint,
+      // Thunk: re-resolved per request so a post-login region change re-targets the
+      // origin without rebuilding the transport. Resolves to `endpoint` when no
+      // region domains are configured (pre-multi-geo behaviour unchanged).
+      baseUrl: () => this.#originForRegion(),
       getToken: () => this.getToken(),
       fetch: config.fetch,
       onRequest: restProbe
     });
-    const baseApi = this.endpoint.replace(/\/+$/, "");
     this.#graphql = createGraphQLTransport({
-      baseUrl: `${baseApi}/grid-api/grid-gql`,
+      baseUrl: () => `${this.#originForRegion()}/grid-api/grid-gql`,
       getToken: () => this.getToken(),
       agencyId: this.agencyId,
       fetch: config.fetch,
       onRequest: graphqlProbe
     });
     this.#graphqlUser = createGraphQLTransport({
-      baseUrl: `${baseApi}/taphub-user-service/th-user-gql`,
+      baseUrl: () => `${this.#originForRegion()}/taphub-user-service/th-user-gql`,
       getToken: () => this.getToken(),
       agencyId: this.agencyId,
       fetch: config.fetch,
       onRequest: graphqlProbe
     });
+    this.#graphqlData = withWrongRegionRetry(this.#graphql, (region) => this.#setRegion(region));
+    this.#graphqlUserData = withWrongRegionRetry(
+      this.#graphqlUser,
+      (region) => this.#setRegion(region)
+    );
     this.user = new UserModule({
-      graphql: this.#graphql,
-      graphqlUser: this.#graphqlUser
+      graphql: this.#graphqlData,
+      graphqlUser: this.#graphqlUserData
     });
     this.auth = new AuthModule({
       rest: this.#rest,
       graphql: this.#graphql,
       graphqlUser: this.#graphqlUser,
+      // Region-routed + wrong-region-retrying transport for token refresh only.
+      graphqlUserData: this.#graphqlUserData,
       setToken: (t, opts) => this.setToken(t, opts),
+      isDemo: () => this.isDemo(),
       agencyId: this.agencyId,
+      // Multi-geo: login sends the client's current (persisted) region; the server
+      // pins it on first join and returns the stored home region thereafter.
+      getRegion: () => this.getRegion(),
+      // Multi-geo: a login that lands on the wrong cluster is rejected with
+      // Auth_WrongRegion + the user's homeRegion; the auth module silently
+      // switches the client's region here and retries once. Kept separate from
+      // setToken so a region redirect never disturbs the auth/token state.
+      setRegion: (region) => this.#setRegion(region),
       onLoginSuccess: () => this.user.refreshCurrencies().then(() => void 0).catch(() => void 0),
       onLogout: () => {
         this.user.clearCurrencies();
@@ -3066,14 +3450,17 @@ var TaphubClient = class {
     const clockSync = new ClockSync();
     this.pair = new PairModule({ graphql: this.#graphql, clockSync });
     this.bid = new BidModule({
-      graphql: this.#graphql,
+      graphql: this.#graphqlData,
       getClockOffset: () => clockSync.getOffset()
     });
     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,
+      // Thunk: re-resolved at connect time so a post-login region change
+      // re-targets the broker without rebuilding the module (multi-geo D4).
+      // Resolves to `mqttEndpoint` when no region MQTT map is configured.
+      mqttEndpoint: () => this.#resolveMqttEndpoint(),
       agencyId: this.agencyId,
       mqttAuth: config.mqttAuth,
       onMqttLifecycle: createMqttProbe(this.network)
@@ -3133,18 +3520,87 @@ var TaphubClient = class {
   getToken() {
     return this.#token;
   }
+  /**
+   * Current API origin, resolved from the home region (multi-geo, design D4).
+   * Trailing slashes trimmed so the service-path suffix composes cleanly. Falls
+   * back to `endpoint` when no region domains are configured or the region is
+   * unknown/absent.
+   */
+  #originForRegion() {
+    return resolveRegionBaseUrl(this.#region, this.#regionDomains, this.endpoint).replace(
+      /\/+$/,
+      ""
+    );
+  }
+  /**
+   * Current MQTT broker endpoint, resolved from the home region (multi-geo,
+   * design D4). Falls back to the configured `mqttEndpoint` when no region MQTT
+   * map is configured or the region is unknown/absent. Only meaningful when
+   * `mqttEndpoint` was configured (otherwise `realtime` is undefined).
+   */
+  #resolveMqttEndpoint() {
+    return resolveRegionBaseUrl(this.#region, this.#regionMqttEndpoints, this.#mqttEndpoint ?? "");
+  }
+  /** The user's home region, once resolved from a login response. */
+  getRegion() {
+    return this.#region;
+  }
+  /**
+   * Set the home region and persist it (survives reloads like the token/isDemo). Shared
+   * by the login path (setToken with a homeRegion) and the wrong-region redirect handler
+   * (task 1.13). A pure region update — it never touches the token or isDemo, so a
+   * mid-session redirect cannot disturb the auth state.
+   */
+  #setRegion(region) {
+    if (this.#region === region) return;
+    const prevMqttEndpoint = this.realtime ? this.#resolveMqttEndpoint() : null;
+    this.#region = region;
+    this.storage.set(this.#regionKey, region);
+    if (this.realtime && prevMqttEndpoint !== null) {
+      const nextMqttEndpoint = this.#resolveMqttEndpoint();
+      if (nextMqttEndpoint !== prevMqttEndpoint) {
+        this.realtime.reconnect();
+      }
+    }
+  }
+  /**
+   * Complete a home-region migration by cutting the client over to `toRegion`
+   * (ux-260730-migration-complete-notify). Intended to be called after a
+   * `migrationCompleted` event (realtime `subscribeMigration`) or an equivalent
+   * poll result confirmed the migration finished — by then the server-side home
+   * region already points at `toRegion`.
+   *
+   * Purpose-named public wrapper over the private `#setRegion` primitive (the
+   * generic region setter stays private so third-party builders cannot
+   * arbitrarily re-target regions). Persists the region and re-targets the
+   * GQL/REST transports; MQTT reconnects only when the resolved broker endpoint
+   * actually changes. Region validation is lenient, matching `region.ts`: an
+   * unknown region is stored as-is and resolves to the default region's
+   * endpoints (enum-fallback, never throws). Idempotent for the already-current
+   * region (no reconnect), and a safe endpoint-level no-op when no region
+   * domain/MQTT maps are configured.
+   */
+  completeRegionMigration(toRegion) {
+    if (toRegion == null || toRegion === "") return;
+    this.#setRegion(toRegion);
+  }
   setToken(token, opts) {
     this.#token = token;
     if (token === null) {
       this.#isDemo = false;
+      this.#region = null;
       this.storage.remove(this.#tokenKey);
       this.storage.remove(this.#isDemoKey);
+      this.storage.remove(this.#regionKey);
       return;
     }
     const isDemo = opts?.isDemo ?? false;
     this.#isDemo = isDemo;
     this.storage.set(this.#tokenKey, token);
     this.storage.set(this.#isDemoKey, isDemo ? "1" : "0");
+    if (opts?.homeRegion !== void 0) {
+      this.#setRegion(opts.homeRegion);
+    }
   }
   isDemo() {
     return this.#isDemo;
@@ -3165,6 +3621,81 @@ var TaphubClient = class {
   }
 };
 
+// src/regionProbe.ts
+var REGION_PROBE_CACHE_KEY = "taphub:region-probe";
+var DEFAULT_PROBE_TTL_SECONDS = 3600;
+var DEFAULT_PROBE_TIMEOUT_MS = 2e3;
+var DEFAULT_PROBE_PATH = "/grid-api/grid-gql";
+var PROBE_QUERY = "{serverTime}";
+function readFreshCache(storage, key, now, ttlSeconds) {
+  try {
+    const raw = storage.get(key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.region !== "string" || typeof parsed.ts !== "number") {
+      return null;
+    }
+    if (now() - parsed.ts >= ttlSeconds * 1e3) return null;
+    return parsed.region;
+  } catch {
+    return null;
+  }
+}
+function writeCache(storage, key, region, now) {
+  try {
+    storage.set(key, JSON.stringify({ region, ts: now() }));
+  } catch {
+  }
+}
+async function probeNearestRegion(domains, opts = {}) {
+  const {
+    fetch: fetchImpl = globalThis.fetch,
+    storage = autoDetectStorage(),
+    ttlSeconds = DEFAULT_PROBE_TTL_SECONDS,
+    timeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+    probePath = DEFAULT_PROBE_PATH,
+    now = Date.now,
+    cacheKey = REGION_PROBE_CACHE_KEY
+  } = opts;
+  const entries = Object.entries(domains ?? {}).filter(
+    (entry) => typeof entry[1] === "string" && entry[1] !== ""
+  );
+  if (entries.length < 2) return null;
+  const cached = readFreshCache(storage, cacheKey, now, ttlSeconds);
+  if (cached !== null && entries.some(([region]) => region === cached)) {
+    return cached;
+  }
+  if (typeof fetchImpl !== "function") return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const winner = await Promise.any(
+      entries.map(async ([region, baseUrl]) => {
+        const url = baseUrl.replace(/\/+$/, "") + probePath;
+        const response = await fetchImpl(url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ query: PROBE_QUERY }),
+          signal: controller.signal
+        });
+        const body = await response.json();
+        const serverTime = body?.data?.serverTime;
+        if (typeof serverTime !== "number") {
+          throw new Error(`region probe: "${region}" returned no serverTime`);
+        }
+        return region;
+      })
+    );
+    writeCache(storage, cacheKey, winner, now);
+    return winner;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+
 // src/modules/realtime/types.ts
 var CANDLE_EVENT = {
   NEW: "new",
@@ -3371,10 +3902,14 @@ function computeBaseline(candleClose, candleTimeSec, cellSizeValue, cellSizeTime
   BidModule,
   CANDLE_EVENT,
   DEFAULT_CHART_HISTORY_LIMIT,
+  DEFAULT_PROBE_TTL_SECONDS,
+  DEFAULT_REGION,
+  KNOWN_REGIONS,
   LeaderboardModule,
   LocaleModule,
   NetworkQualityMonitor,
   PairModule,
+  REGION_PROBE_CACHE_KEY,
   RealtimeModule,
   TaphubAuthError,
   TaphubClient,
@@ -3395,6 +3930,7 @@ function computeBaseline(candleClose, candleTimeSec, cellSizeValue, cellSizeTime
   computeBaseline,
   errorFunction,
   isCancelled,
+  isKnownRegion,
   isLoss,
   isPending,
   isTerminal,
@@ -3403,5 +3939,7 @@ function computeBaseline(candleClose, candleTimeSec, cellSizeValue, cellSizeTime
   normalPDF,
   normaliseLang,
   pairIdFromBidResultTopic,
+  probeNearestRegion,
+  resolveRegionBaseUrl,
   roundCoefToSignificantDigits
 });