@taphubhq/sdk-core 0.25.5 → 0.26.0

package/dist/index.d.ts

@@ -1,5 +1,49 @@
 import EventEmitter from 'eventemitter3';
 
+/**
+ * Home-region → API base-URL resolution (multi-geo, design D4: domain-per-region).
+ *
+ * The region → domain map is caller-supplied config (see
+ * {@link TaphubClientConfig.regionDomains}) — hosts are NEVER hardcoded here. An
+ * unknown or missing region value degrades to the default region rather than
+ * crashing the client (defensive client coding): a server may one day return a
+ * region a shipped build does not yet recognise, and that must not break the app.
+ */
+/**
+ * Region set for Phase 1 (design D4: `sg`, `eu`, `jp`). Kept as a `const` tuple so
+ * {@link KnownRegion} is derived from it and the two never drift apart.
+ */
+declare const KNOWN_REGIONS: readonly ["sg", "eu", "jp"];
+type KnownRegion = (typeof KNOWN_REGIONS)[number];
+/** Default home region (design/tasks: default `sg`) — also the enum-fallback target. */
+declare const DEFAULT_REGION: KnownRegion;
+/**
+ * Region → API base URL. Config-driven; supplied by the host app from env, never
+ * hardcoded. Keyed by region string so an unknown key is simply absent (and
+ * resolution falls back), rather than a type error.
+ */
+type RegionDomainMap = Partial<Record<string, string>>;
+/** Narrowing guard: is `region` one of the build's known regions? */
+declare function isKnownRegion(region: string | null | undefined): region is KnownRegion;
+/**
+ * Resolve the API base URL for a home region.
+ *
+ * - **Absent region** (`null`/`undefined`/`''`) → `fallbackBaseUrl` unchanged. A
+ *   login response that carries no region keeps the client on its construction-time
+ *   endpoint (additive / backward-compatible).
+ * - **Known region** present in `domains` → that region's domain.
+ * - **Unknown non-empty region** value → the default region's domain (enum-fallback,
+ *   defensive client coding — a server-sent region a shipped build does not
+ *   recognise must not crash it).
+ * - Known region absent from the map → the default region's domain when configured,
+ *   otherwise `fallbackBaseUrl`.
+ *
+ * Never throws. When `domains` is undefined/empty (the pre-multi-geo default) it
+ * always returns `fallbackBaseUrl`, so a client with no region config behaves
+ * exactly as before.
+ */
+declare function resolveRegionBaseUrl(region: string | null | undefined, domains: RegionDomainMap | undefined, fallbackBaseUrl: string): string;
+
 interface TaphubStorageAdapter {
     get(key: string): string | null;
     set(key: string, value: string): void;
@@ -28,10 +72,27 @@ interface TaphubClientConfig {
     agencyId: string;
     endpoint: string;
     mqttEndpoint?: string;
+    /**
+     * Multi-geo (design D4): region → MQTT broker endpoint. Same shape/semantics as
+     * {@link regionDomains} but for the realtime (MQTT) connection. When present, the
+     * realtime module targets the endpoint resolved from the user's home region; a
+     * login that changes the region reconnects to the new region's broker. When
+     * omitted, the single `mqttEndpoint` is used for every region — i.e. the
+     * pre-multi-geo behaviour is unchanged.
+     */
+    regionMqttEndpoints?: RegionDomainMap;
     /** Optional MQTT broker credentials. Ignored when `mqttEndpoint` is absent. */
     mqttAuth?: MqttAuthConfig;
     storage?: TaphubStorageAdapter;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Multi-geo (design D4): region → API base URL. Supplied by the host app from
+     * env (never hardcoded hosts). When present, once login resolves the user's home
+     * region, subsequent GraphQL/REST calls target that region's domain; an unknown
+     * region falls back to the default region. When omitted, the client always uses
+     * `endpoint` — i.e. the pre-multi-geo behaviour is unchanged.
+     */
+    regionDomains?: RegionDomainMap;
 }
 
 type SignalSource = 'graphql' | 'rest' | 'mqtt' | 'browser' | 'connection';
@@ -155,16 +216,64 @@ interface LoginResult {
     accessToken: string;
     user: User;
     isDemo: boolean;
+    /**
+     * The user's home region (multi-geo, design D4/R6), when the login response
+     * carries it. Optional and additive: a BE that does not yet return a region
+     * leaves this `undefined`, and the client keeps using its default base URL.
+     */
+    homeRegion?: string;
+}
+/**
+ * Result of a successful {@link AuthModule.refreshTapHubToken}: the rotated token
+ * pair. The rotation contract requires presenting the NEW refresh token on the
+ * next refresh, so callers must persist both. Demo users never reach this path —
+ * `refreshTapHubToken` rejects with `Refresh_DemoNotSupported` for them.
+ */
+interface RefreshTokenResult {
+    taphubToken: string;
+    refreshToken: string;
 }
 
 interface AuthModuleDeps {
     rest: RestTransport;
     graphql: GraphQLTransport;
     graphqlUser: GraphQLTransport;
+    /**
+     * Region-routed, Auth_WrongRegion-retrying variant of `graphqlUser`, used by
+     * {@link AuthModule.refreshTapHubToken}. Login keeps using the raw `graphqlUser`
+     * because it runs its OWN wrong-region retry (`loginWithSession`); wiring the
+     * wrapped transport there would double-retry. Optional: falls back to
+     * `graphqlUser` (unwrapped) when not provided.
+     */
+    graphqlUserData?: GraphQLTransport;
     setToken: (token: string | null, opts?: {
         isDemo?: boolean;
+        homeRegion?: string;
     }) => void;
+    /**
+     * Whether the current session is a demo user. Demo users have no refresh path
+     * (see design D2/D4/D7), so {@link AuthModule.refreshTapHubToken} short-circuits
+     * for them instead of hitting the network. Optional: defaults to a non-demo
+     * session (`() => false`).
+     */
+    isDemo?: () => boolean;
     agencyId: string;
+    /**
+     * Multi-geo: the client's CURRENT region (e.g. persisted from a previous login),
+     * sent with the login request. First join → the server registers it as the home
+     * region; existing user → the stored home region wins. Optional (single-region
+     * clients never set a region and the server falls back to its default).
+     */
+    getRegion?: () => string | null;
+    /**
+     * Multi-geo: switch the client's home region (and persist it). Called by the
+     * silent Auth_WrongRegion redirect — the server rejected a login on the wrong
+     * cluster and told us the user's home region, so we set it here and retry the
+     * SAME login once (the user-service base-URL thunk then re-resolves to the home
+     * region's domain). Kept distinct from `setToken` so a redirect never touches
+     * the token/isDemo state. Optional: single-region clients never wire it.
+     */
+    setRegion?: (region: string) => void;
     onLoginSuccess?: () => Promise<void>;
     onLogout?: () => void | Promise<void>;
 }
@@ -180,7 +289,32 @@ declare class AuthModule {
     }): Promise<LoginResult>;
     loginWithSession(sessionToken: string, opts?: {
         signal?: AbortSignal;
+        region?: string;
     }): Promise<LoginResult>;
+    /**
+     * 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: string, opts?: {
+        clientMeta?: string;
+        signal?: AbortSignal;
+    }): Promise<RefreshTokenResult>;
     logout(): Promise<void>;
 }
 
@@ -691,21 +825,39 @@ interface Constraints {
     maxCoef: number;
 }
 interface PairInfo {
-    /** game_pairs.id — catalog identifier for this pair within a gameplay. */
+    /**
+     * game_pairs.id — the catalog identifier for this pair, always the bare
+     * slash-free form (e.g. `"grid-ETH-USD"`), never the agency composite.
+     *
+     * The server returns `"{agencyId}:{pairId}"` here for callers with an agency
+     * JWT; the SDK strips that prefix so this value is identical across auth
+     * modes and can be passed straight back as a `pairId` argument. The composite
+     * is preserved in `agencyPairId`.
+     */
     id: string;
     /** Trading pair symbol, e.g. "BTC/USD". */
     pair: string;
-    /** ID of the gameplay this pair belongs to. Use as `gameplaySlug` in game.get(). */
+    /**
+     * ID of the gameplay this pair belongs to.
+     * @deprecated grid-api retired this field from `type Pair`; it is always `''`.
+     */
     gameplayId: string;
-    /** Human-readable gameplay name. */
+    /**
+     * Human-readable gameplay name.
+     * @deprecated grid-api retired this field from `type Pair`; it is always `''`.
+     */
     gameplayName: string;
     /** Price feed source, e.g. "binance". */
     source: string;
     /**
-     * agency_game_pairs.id — the runtime game ID for this agency.
-     * Present only when the caller is authenticated with a valid JWT.
-     * Use directly as `gameId` in MQTT topic `game/{gameId}/candle`.
-     * Null when called without authentication.
+     * agency_game_pairs.id — the runtime game ID for this agency, shaped
+     * `"{agencyId}:{pairId}"`. Use directly as `gameId` in MQTT topic
+     * `game/{gameId}/candle`.
+     *
+     * grid-api retired the dedicated wire field and now returns this value as
+     * `Pair.id` instead, but only for callers with an agency JWT. Anonymous
+     * callers receive the bare catalog id in `id`, and this property is `null` —
+     * do not substitute `id` for it, that id has no MQTT topic.
      */
     agencyPairId: string | null;
 }
@@ -740,8 +892,11 @@ declare class PairModule {
     /**
      * 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' });
@@ -834,7 +989,20 @@ interface MqttWireWalletBalance {
     currency: string;
     reason: string;
 }
-type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats | MqttWireWalletBalance;
+/**
+ * Wire payload on the user-scoped migration topic `user/{userId}/migration`,
+ * published by `taphub-user-service` when a home-region migration completes
+ * (ux-260730-migration-complete-notify). camelCase on the wire; `completedAt`
+ * is unix epoch SECONDS.
+ */
+interface MqttWireMigrationCompleted {
+    type: 'migration_completed';
+    migrationId: string;
+    fromRegion: string;
+    toRegion: string;
+    completedAt: number;
+}
+type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats | MqttWireWalletBalance | MqttWireMigrationCompleted;
 type MqttMessageHandler = (gameId: string, topic: string, payload: MqttWirePayload) => void;
 type MqttErrorHandler = (err: Error) => void;
 type MqttLifecycleEvent = {
@@ -857,6 +1025,7 @@ 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;
+type MqttMigrationMessageHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
      * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
@@ -910,6 +1079,25 @@ interface MqttTransport {
     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;
+    /**
+     * Subscribe to the user-scoped migration completion stream, topic
+     * `user/{userId}/migration` (ux-260730). Independent of any game subscription —
+     * NOT torn down by `unsubscribeAll`. Idempotent per `userId`. Subscribed at
+     * QoS 1 to match the publisher (redelivery on reconnect beats silent loss);
+     * the publisher also retains the message so a late subscriber still sees it.
+     */
+    subscribeMigration(userId: string, onMessage: MqttMigrationMessageHandler, onError: MqttErrorHandler): void;
+    /** Tear down the migration subscription for a `userId`. No-op if absent. */
+    unsubscribeMigration(userId: string): void;
+    /**
+     * Reconnect the underlying MQTT socket, re-resolving the endpoint (multi-geo:
+     * the endpoint may be a thunk that now points at a different region's broker).
+     * All tracked subscriptions are preserved and re-declared on the fresh
+     * connection's `connect` event. No-op when not currently connected — the next
+     * `ensureConnected` (triggered by any subscribe) already resolves the fresh
+     * endpoint.
+     */
+    reconnect(): void;
     close(): void;
 }
 
@@ -1045,6 +1233,22 @@ interface MqttIdealConfigEvent {
     currentPrice: number;
     reason: string;
 }
+/**
+ * Home-region migration completion event from the user-scoped MQTT topic
+ * `user/{userId}/migration` (ux-260730-migration-complete-notify). Published by
+ * taphub-user-service (QoS 1, retained with TTL) when the migration saga reaches
+ * COMPLETED — by then the user's home region already points at `toRegion`.
+ * Consumers match `toRegion` against their pending migration target and then
+ * complete the cutover via `TaphubClient.completeRegionMigration(toRegion)`.
+ */
+interface MigrationCompletedEvent {
+    type: 'migration_completed';
+    migrationId: string;
+    fromRegion: string;
+    toRegion: string;
+    /** Unix epoch **seconds**. */
+    completedAt: number;
+}
 /**
  * Live per-pair stats tick from the public stream
  * `public/agency/{aid}/pair/{pairId}/stats`. The backend suppresses
@@ -1075,6 +1279,22 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
     constructor(gameId: string);
 }
 
+interface MigrationChannelEvents {
+    migrationCompleted: [MigrationCompletedEvent];
+    error: [Error];
+}
+/**
+ * User-scoped migration channel (ux-260730). Emits `migrationCompleted` when the
+ * user's home-region migration finishes, from `user/{userId}/migration`. Mirror
+ * of {@link WalletChannel}: keyed by `userId`, independent of any game
+ * subscription. Intended to be held only while the client is in the migrating
+ * state (subscribe on trigger/resume, unsubscribe on completion/logout).
+ */
+declare class MigrationChannel extends EventEmitter<MigrationChannelEvents> {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
 interface UserBidsChannelEvents {
     bidWon: [MqttBidWonEvent];
     bidLost: [MqttBidLostEvent];
@@ -1108,7 +1328,12 @@ declare class WalletChannel extends EventEmitter<WalletChannelEvents> {
 }
 
 interface RealtimeModuleOptions {
-    mqttEndpoint: string;
+    /**
+     * MQTT broker endpoint. May be a thunk (multi-geo, design D4): resolved at
+     * connect time so {@link RealtimeModule.reconnect} can re-target the broker to
+     * the user's home-region endpoint after a login region switch.
+     */
+    mqttEndpoint: string | (() => string);
     /**
      * The client's own agency id. Threaded so `subscribeAgencyPairStats` can
      * scope the stats topic to this agency without accepting a target agency from
@@ -1179,6 +1404,23 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
      * down the wildcard topic and removes the channel only at zero. No-op if absent.
      */
     unsubscribeUserBids(userId: string): void;
+    /**
+     * 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: string): MigrationChannel;
+    /**
+     * 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: 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 —
@@ -1195,6 +1437,13 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
     subscribeAgencyPairStats(pairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
     /** Unsubscribe from the per-pair stats stream for the client's own agency. */
     unsubscribeAgencyPairStats(pairId: string): void;
+    /**
+     * 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(): void;
     disconnect(): void;
 }
 
@@ -1256,6 +1505,17 @@ declare class UserModule {
     }): Promise<UserPnL>;
     wallets(opts?: RequestOpts): Promise<Wallet[]>;
     walletByCurrency(currency: string, opts?: RequestOpts): Promise<Wallet>;
+    /**
+     * 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.
+     */
+    requestRegionMigration(toRegion: string, opts?: RequestOpts): Promise<{
+        migrationId: string;
+    }>;
     get currencies(): Currency[] | null;
     refreshCurrencies(): Promise<Currency[]>;
     clearCurrencies(): void;
@@ -1338,8 +1598,29 @@ declare class TaphubClient {
     private bus;
     constructor(config: TaphubClientConfig);
     getToken(): string | null;
+    /** The user's home region, once resolved from a login response. */
+    getRegion(): string | null;
+    /**
+     * 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: KnownRegion | (string & {})): void;
     setToken(token: string | null, opts?: {
         isDemo?: boolean;
+        homeRegion?: string;
     }): void;
     isDemo(): boolean;
     /** @internal Used by module integrations to access the REST transport. Not part of the public API. */
@@ -1350,6 +1631,73 @@ declare class TaphubClient {
     off<K extends keyof TaphubEventMap & string>(event: K, handler: (payload: TaphubEventMap[K]) => void): void;
 }
 
+/**
+ * Nearest-region latency probe (multi-geo, Solution 3 — first-join geo routing).
+ *
+ * The browser is the only vantage point that can measure real per-region latency
+ * (it holds a network path to every region domain). This module runs one cheap,
+ * parallel round of requests and proposes the **first region to answer with a
+ * valid body** — an approximate lowest-latency signal, which is sufficient because
+ * exact nearness is a non-goal (a fast-responding region is what we want, not the
+ * provably-nearest one).
+ *
+ * What it measures: the `{serverTime}` query on each region's grid-api GraphQL
+ * endpoint — the cheapest call that proves the request reached that region's
+ * backend rather than an edge in front of it. The winner must return a PARSEABLE
+ * body carrying a numeric `serverTime`, not merely respond first: an edge
+ * rejection (404 page, WAF challenge, gateway error) comes back in milliseconds
+ * from the nearest PoP and would otherwise beat every genuine round trip and win
+ * the race.
+ *
+ * The result is only ever a *hint*: the caller sends it to the builder backend
+ * (`taptrading-api`) inside `clientMeta.preferredRegion`, where it is validated
+ * against the deployed-region set before it can influence the user's home-region
+ * pin. This module never decides anything on its own and never throws — geo must
+ * not be able to fail a login.
+ */
+
+/** Stable storage key for the throttle cache. Not agency-scoped — the nearest
+ * region is a property of the user's network geography, the same for every agency. */
+declare const REGION_PROBE_CACHE_KEY = "taphub:region-probe";
+/** Default throttle window — re-probe at most once per hour (config overrides it). */
+declare const DEFAULT_PROBE_TTL_SECONDS = 3600;
+interface ProbeNearestRegionOptions {
+    /** Fetch implementation (injectable for tests / non-browser hosts). */
+    fetch?: typeof globalThis.fetch;
+    /** Storage for the throttle cache (defaults to the SDK's auto-detected storage). */
+    storage?: TaphubStorageAdapter;
+    /** Throttle window in seconds — a cached result younger than this skips the probe. */
+    ttlSeconds?: number;
+    /** Overall cap for one probe round; nothing responding in time → `null`. */
+    timeoutMs?: number;
+    /** Probe path appended to each region base URL. */
+    probePath?: string;
+    /** Clock, injectable for deterministic cache-expiry tests. */
+    now?: () => number;
+    /** Cache key override (tests / multi-tenant hosts). */
+    cacheKey?: string;
+}
+/**
+ * Probe the configured regions and return the fastest-responding one, or `null`.
+ *
+ * Behaviour:
+ * - Fewer than two configured regions → `null` (nothing to choose; the caller
+ *   sends no hint and the server uses its default region).
+ * - A fresh cached result (younger than `ttlSeconds`) is reused without any
+ *   network probe — this throttles repeated app boots / login-modal opens by an
+ *   un-pinned user to at most one probe round per TTL window.
+ * - Otherwise one parallel round of `POST <domain><probePath>` runs, each request
+ *   carrying the `{serverTime}` query; the first region to return a parseable body
+ *   with a numeric `serverTime` wins and is cached. A region that answers fast but
+ *   unparseably (an edge 404/error page) loses the race rather than winning it.
+ *   The response body has to be readable, so this is a normal CORS request — the
+ *   region endpoints must allow the app origin (they already do: the app posts to
+ *   this same endpoint).
+ * - Any failure — all endpoints erroring, a timeout, a thrown fetch, a storage
+ *   error — resolves to `null`. This function never rejects.
+ */
+declare function probeNearestRegion(domains: RegionDomainMap | undefined, opts?: ProbeNearestRegionOptions): Promise<string | null>;
+
 declare class TaphubError extends Error {
     readonly code: string;
     readonly details?: unknown;
@@ -1429,7 +1777,75 @@ declare function errorFunction(x: number): number;
 declare function normalCDF(x: number): number;
 declare function normalPDF(x: number): number;
 declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number, tolerance?: number, maxDepth?: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+interface CoefficientInput {
+    time1: number;
+    time2: number;
+    price1: number;
+    price2: number;
+    candleTime: number;
+    candleClose: number;
+    volatility: number;
+    coefMults: number[];
+    cellSizeTime: number;
+    candleSize: number;
+    minCoef?: number;
+}
+/**
+ * First-passage hitting probability: chance the price visits [price1, price2]
+ * at any point during [time1, time2], given GBM dynamics.
+ *
+ * P_hit = P_inside + P_from_above + P_from_below
+ *
+ * Matches Go backend algorithm.
+ */
+declare function calculateProbHit(time1: number, time2: number, price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+declare function calculateCoefficientWrapper(params: CoefficientInput): number;
+declare function roundCoefToSignificantDigits(value: number): number;
+declare function computeBaseline(candleClose: number, candleTimeSec: number, cellSizeValue: number, cellSizeTime: number, candleSize: number): {
+    baseline: number;
+    baselineTime: number;
+};
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, CANDLE_EVENT, type CancelBidResult, type Candle, type CandleEventType, type Constraints, type Currency, DEFAULT_CHART_HISTORY_LIMIT, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, 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, normaliseLang, pairIdFromBidResultTopic };
+export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, CANDLE_EVENT, type CancelBidResult, type Candle, type CandleEventType, type CoefficientInput, type Constraints, type Currency, DEFAULT_CHART_HISTORY_LIMIT, DEFAULT_PROBE_TTL_SECONDS, DEFAULT_REGION, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, GameChannel, type GameConfig, type GridConfig, KNOWN_REGIONS, type KnownRegion, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, MigrationChannel, type MigrationChannelEvents, type MigrationCompletedEvent, 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 ProbeNearestRegionOptions, REGION_PROBE_CACHE_KEY, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type RefreshTokenResult, type RegionDomainMap, 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, calculateCoefficientWrapper, calculateProbHit, calculateProbWin, calculateProbWin_v2, computeBaseline, errorFunction, isCancelled, isKnownRegion, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, normaliseLang, pairIdFromBidResultTopic, probeNearestRegion, resolveRegionBaseUrl, roundCoefToSignificantDigits };