@taphubhq/sdk-core 0.25.3 → 0.25.5

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(index_exports, {
   AgencyPairModule: () => AgencyPairModule,
   AuthModule: () => AuthModule,
   BidModule: () => BidModule,
+  CANDLE_EVENT: () => CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT: () => DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule: () => LeaderboardModule,
   LocaleModule: () => LocaleModule,
   NetworkQualityMonitor: () => NetworkQualityMonitor,
@@ -60,6 +62,7 @@ __export(index_exports, {
   isWin: () => isWin,
   normalCDF: () => normalCDF,
   normalPDF: () => normalPDF,
+  normaliseLang: () => normaliseLang,
   pairIdFromBidResultTopic: () => pairIdFromBidResultTopic
 });
 module.exports = __toCommonJS(index_exports);
@@ -781,6 +784,39 @@ var LeaderboardModule = class {
   }
 };
 
+// src/modules/locale/errorMessages.ts
+function normaliseLang(tag) {
+  const clean = (tag || "").trim().toLowerCase();
+  if (!clean) return "en";
+  if (clean === "zh" || clean.startsWith("zh-")) {
+    if (/(^|-)(hant|tw|hk|mo)(-|$)/.test(clean)) return "zh-TW";
+    return "zh-CN";
+  }
+  return clean.split("-")[0] || "en";
+}
+function pickStringEntries(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") out[key] = entry;
+  }
+  return out;
+}
+function interpolate(template, meta) {
+  const filled = template.replace(/\{(\w+)\}/g, (_match, key) => {
+    const value = meta?.[key];
+    if (value === void 0 || value === null) return "";
+    return String(value);
+  });
+  return filled.replace(/\s{2,}/g, " ").trim();
+}
+function resolveErrorMessage(code, catalog, fallback, meta) {
+  const row = catalog?.[code];
+  if (typeof row !== "string" || row.trim() === "") return fallback;
+  const filled = interpolate(row, meta);
+  return filled === "" ? fallback : filled;
+}
+
 // src/modules/locale/normalise.ts
 function normaliseLocaleResponse(node) {
   let translations = null;
@@ -805,6 +841,14 @@ function normaliseLocaleResponse(node) {
     translations
   };
 }
+function normaliseErrorMessagesResponse(node) {
+  return {
+    lang: node.lang,
+    version: node.version,
+    notModified: node.notModified,
+    messages: node.messages === null ? null : pickStringEntries(node.messages)
+  };
+}
 function normaliseRefreshLocalesPayload(node) {
   let versions;
   try {
@@ -838,10 +882,33 @@ var REFRESH_LOCALES_MUTATION = `mutation RefreshLocales {
     versions
   }
 }`;
+var ERROR_MESSAGES_QUERY = `query ErrorMessages($input: LocalesInput!) {
+  errorMessages(input: $input) {
+    lang
+    version
+    notModified
+    messages
+  }
+}`;
 
 // src/modules/locale/index.ts
 var LocaleModule = class {
   #graphql;
+  /**
+   * The loaded error-message catalog. Instance state, not module state, so two
+   * clients in one process (tests, multi-tenant hosts) never share a catalog.
+   *
+   * Null until a load succeeds. It is NEVER reset to null afterwards — a failed
+   * refresh keeps the last-known-good copy, because losing all error copy is
+   * strictly worse than showing slightly stale copy.
+   */
+  #errorMessages = null;
+  /**
+   * In-flight catalog loads, keyed by normalised language. Collapses concurrent
+   * callers onto one request; entries are removed as soon as a load settles, so
+   * this never becomes a cache of results (or of failures).
+   */
+  #errorMessagesInFlight = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
@@ -864,6 +931,94 @@ var LocaleModule = class {
     const body = await this.#graphql.request(LOCALES_QUERY, { input }, opts);
     return normaliseLocaleResponse(body.locales);
   }
+  /**
+   * Fetch the error-message catalog for a single language.
+   *
+   * The throwing sibling of {@link loadErrorMessages}: errors surface as
+   * TaphubError subclasses with backend `extensions.code` values
+   * (`LangNotSupported`, `FeatureDisabled`, …), because a caller doing an
+   * explicit fetch wants to see why it failed. Hosts that just want copy on
+   * screen should call `loadErrorMessages` instead.
+   *
+   * `lang` is passed through as given — normalisation is `loadErrorMessages`'
+   * job, so an explicit caller keeps full control of the tag.
+   */
+  async getErrorMessages(lang, knownVersion, opts) {
+    const input = { lang };
+    if (knownVersion !== void 0 && knownVersion !== "") {
+      input.knownVersion = knownVersion;
+    }
+    const body = await this.#graphql.request(
+      ERROR_MESSAGES_QUERY,
+      { input },
+      opts
+    );
+    return normaliseErrorMessagesResponse(body.errorMessages);
+  }
+  /**
+   * Load the error-message catalog for `lang` into this client.
+   *
+   * Background hydration with nobody waiting on it, so it **never throws and
+   * never rejects**. Every failure path — network error, backend down,
+   * `FeatureDisabled` when the source sheet is not configured, an unsupported
+   * tag, a malformed body — leaves the previously loaded catalog in place.
+   * Failing to translate an error must not itself become an error.
+   *
+   * The tag is normalised first (region dropped, Chinese scripts kept apart),
+   * so a host can hand over `navigator.language` untouched.
+   *
+   * Concurrent calls for the same language share one request. The catalog lives
+   * on the client while the thing that triggers a load (a mounted provider)
+   * lives a level below, so two providers sharing one client would otherwise
+   * fetch the same bytes into the same place twice.
+   *
+   * This is dedup, not caching — it lasts only while a request is in flight. A
+   * host calling again after one settles gets a fresh fetch.
+   *
+   * Deliberately takes NO AbortSignal. A follower piggybacking on someone
+   * else's request would otherwise have its outcome decided by whether that
+   * other caller happened to unmount first. Letting a background hydration run
+   * to completion costs one small request; stranding a caller costs all the
+   * error copy on screen.
+   *
+   * No persistence and no polling: the host decides when to call this. The
+   * React provider calls it on mount and on language change.
+   */
+  async loadErrorMessages(lang) {
+    const key = normaliseLang(lang);
+    const inFlight = this.#errorMessagesInFlight.get(key);
+    if (inFlight) return inFlight;
+    const run = (async () => {
+      try {
+        const res = await this.getErrorMessages(key);
+        if (res.notModified || res.messages === null) return;
+        if (Object.keys(res.messages).length === 0) return;
+        this.#errorMessages = res.messages;
+      } catch {
+      } finally {
+        this.#errorMessagesInFlight.delete(key);
+      }
+    })();
+    this.#errorMessagesInFlight.set(key, run);
+    return run;
+  }
+  /**
+   * The sentence to show for a backend error `code`.
+   *
+   * **Synchronous by design** — error copy is read when a toast is built, inside
+   * a `catch` or an error handler, where React hooks are illegal. That is why
+   * this is a plain method and not a hook.
+   *
+   * Returns `fallback` whenever the catalog cannot produce a usable sentence: no
+   * catalog loaded yet, no row for the code, or a blank row. Never returns an
+   * empty string, and never returns the raw code.
+   *
+   * `meta` fills `{name}` placeholders in a catalog row; any placeholder left
+   * unfilled is stripped, so raw braces never reach the user.
+   */
+  errorMessage(code, fallback, meta) {
+    return resolveErrorMessage(code, this.#errorMessages, fallback, meta);
+  }
   /**
    * Trigger an admin refresh — backend re-pulls the source Sheet, invalidates
    * its cache, and writes fresh entries for every supported language.
@@ -994,6 +1149,9 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
   }
 }`;
 
+// src/modules/pair/types.ts
+var DEFAULT_CHART_HISTORY_LIMIT = 600;
+
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
@@ -1051,11 +1209,8 @@ var PairModule = class {
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
   // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
-  async chartHistory(pairId, limit, opts) {
-    const variables = { pairId };
-    if (limit !== void 0) {
-      variables.limit = limit;
-    }
+  async chartHistory(pairId, limit = DEFAULT_CHART_HISTORY_LIMIT, opts) {
+    const variables = { pairId, limit };
     const body = await this.#graphql.request(
       CHART_HISTORY_QUERY,
       variables,
@@ -3006,6 +3161,12 @@ var TaphubClient = class {
   }
 };
 
+// src/modules/realtime/types.ts
+var CANDLE_EVENT = {
+  NEW: "new",
+  UPDATE: "update"
+};
+
 // src/utils/coefficient.ts
 function errorFunction(x) {
   const a1 = 0.254829592;
@@ -3095,6 +3256,8 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   AgencyPairModule,
   AuthModule,
   BidModule,
+  CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule,
   LocaleModule,
   NetworkQualityMonitor,
@@ -3122,5 +3285,6 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   isWin,
   normalCDF,
   normalPDF,
+  normaliseLang,
   pairIdFromBidResultTopic
 });

package/dist/index.d.mts

@@ -454,6 +454,57 @@ interface LocaleRefreshResult {
     refreshed: string[];
     versions: Record<string, string>;
 }
+/**
+ * Flat error-message catalog for a single language: backend error code → sentence.
+ *
+ * Keys are the `extensions.code` values the backend returns on a rejection
+ * (`Bid_RateLimited`, `Wallet_WithdrawNetworkUnavailable`, …). Values may contain
+ * `{name}` placeholders filled from the error's meta at lookup time.
+ */
+type ErrorMessageCatalog = Record<string, string>;
+/**
+ * Values available to fill a catalog row's `{name}` placeholders — normally the
+ * `meta` carried by the backend error. Values are stringified as-is; a caller who
+ * needs specific formatting (decimal places, currency) should format before passing.
+ */
+type ErrorMessageMeta = Record<string, unknown>;
+/**
+ * Public response shape from LocaleModule.getErrorMessages().
+ *
+ * Mirrors {@link LocaleResponse}, with one wire-level difference: `messages`
+ * arrives as a real JSON object rather than a JSON-string, so there is no parse
+ * step. Non-string values are dropped during normalisation.
+ *
+ * `messages` is null when `notModified` is true (caller keeps prior state).
+ */
+interface ErrorMessagesResponse {
+    lang: string;
+    version: string;
+    notModified: boolean;
+    messages: ErrorMessageCatalog | null;
+}
+
+/**
+ * Pure helpers behind the error-message catalog.
+ *
+ * Kept free of I/O and of module state so the precedence rule, the language
+ * mapping and the template filling are all testable without a transport.
+ */
+
+/**
+ * Reduce a host language tag to the catalog's column name.
+ *
+ * The sheet's columns are en, vi, es, hi, zh-TW, zh-CN, ja, pt, fr, de, it, tr,
+ * ko, ar. Only Chinese needs more than the primary subtag: zh-TW and zh-CN are
+ * different SCRIPTS, so collapsing both to "zh" would show Simplified text to a
+ * Traditional reader. Everything else drops its region.
+ *
+ * The supported-language list is deliberately NOT duplicated here — the server
+ * owns it, and an unsupported tag simply fails the fetch and leaves prior copy
+ * in place, which is the same outcome a stale local list would produce with
+ * more code.
+ */
+declare function normaliseLang(tag: string): string;
 
 interface LocaleModuleDeps {
     graphql: GraphQLTransport;
@@ -484,6 +535,66 @@ declare class LocaleModule {
     get(lang: string, knownVersion?: string, opts?: {
         signal?: AbortSignal;
     }): Promise<LocaleResponse>;
+    /**
+     * Fetch the error-message catalog for a single language.
+     *
+     * The throwing sibling of {@link loadErrorMessages}: errors surface as
+     * TaphubError subclasses with backend `extensions.code` values
+     * (`LangNotSupported`, `FeatureDisabled`, …), because a caller doing an
+     * explicit fetch wants to see why it failed. Hosts that just want copy on
+     * screen should call `loadErrorMessages` instead.
+     *
+     * `lang` is passed through as given — normalisation is `loadErrorMessages`'
+     * job, so an explicit caller keeps full control of the tag.
+     */
+    getErrorMessages(lang: string, knownVersion?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ErrorMessagesResponse>;
+    /**
+     * Load the error-message catalog for `lang` into this client.
+     *
+     * Background hydration with nobody waiting on it, so it **never throws and
+     * never rejects**. Every failure path — network error, backend down,
+     * `FeatureDisabled` when the source sheet is not configured, an unsupported
+     * tag, a malformed body — leaves the previously loaded catalog in place.
+     * Failing to translate an error must not itself become an error.
+     *
+     * The tag is normalised first (region dropped, Chinese scripts kept apart),
+     * so a host can hand over `navigator.language` untouched.
+     *
+     * Concurrent calls for the same language share one request. The catalog lives
+     * on the client while the thing that triggers a load (a mounted provider)
+     * lives a level below, so two providers sharing one client would otherwise
+     * fetch the same bytes into the same place twice.
+     *
+     * This is dedup, not caching — it lasts only while a request is in flight. A
+     * host calling again after one settles gets a fresh fetch.
+     *
+     * Deliberately takes NO AbortSignal. A follower piggybacking on someone
+     * else's request would otherwise have its outcome decided by whether that
+     * other caller happened to unmount first. Letting a background hydration run
+     * to completion costs one small request; stranding a caller costs all the
+     * error copy on screen.
+     *
+     * No persistence and no polling: the host decides when to call this. The
+     * React provider calls it on mount and on language change.
+     */
+    loadErrorMessages(lang: string): Promise<void>;
+    /**
+     * The sentence to show for a backend error `code`.
+     *
+     * **Synchronous by design** — error copy is read when a toast is built, inside
+     * a `catch` or an error handler, where React hooks are illegal. That is why
+     * this is a plain method and not a hook.
+     *
+     * Returns `fallback` whenever the catalog cannot produce a usable sentence: no
+     * catalog loaded yet, no row for the code, or a blank row. Never returns an
+     * empty string, and never returns the raw code.
+     *
+     * `meta` fills `{name}` placeholders in a catalog row; any placeholder left
+     * unfilled is stripped, so raw braces never reach the user.
+     */
+    errorMessage(code: string, fallback: string, meta?: ErrorMessageMeta): string;
     /**
      * Trigger an admin refresh — backend re-pulls the source Sheet, invalidates
      * its cache, and writes fresh entries for every supported language.
@@ -598,6 +709,13 @@ interface PairInfo {
      */
     agencyPairId: string | null;
 }
+/**
+ * Default number of candles fetched on initial chart load when the caller does
+ * not pass an explicit limit. The server clamps any request to its cache size
+ * (grid-api services.ChartHistoryMaxLimit = 1500), so this is purely how much
+ * history the chart shows by default — kept lower than the cap for faster init.
+ */
+declare const DEFAULT_CHART_HISTORY_LIMIT = 600;
 interface Candle {
     /** Unix epoch SECONDS (not ms). Multiply by 1000 for JS Date. */
     time: number;
@@ -795,6 +913,16 @@ interface MqttTransport {
     close(): void;
 }
 
+/**
+ * Candle tick kind. `new` = a fresh bar opened; `update` = the current bar was
+ * revised. Exported as named constants so consumers compare against these
+ * instead of bare string literals (a typo on a literal fails silently).
+ */
+declare const CANDLE_EVENT: {
+    readonly NEW: "new";
+    readonly UPDATE: "update";
+};
+type CandleEventType = (typeof CANDLE_EVENT)[keyof typeof CANDLE_EVENT];
 /**
  * Candle tick from MQTT.
  * WARNING: `time` is Unix epoch MILLISECONDS.
@@ -802,7 +930,7 @@ interface MqttTransport {
  * Do NOT multiply MQTT candle time by 1000.
  */
 interface MqttCandleEvent {
-    type: 'new' | 'update';
+    type: CandleEventType;
     /** Unix epoch **milliseconds** — differs from GQL chartHistory (seconds) */
     time: number;
     o: number;
@@ -1304,4 +1432,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, pairIdFromBidResultTopic };
+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 };

package/dist/index.d.ts

@@ -454,6 +454,57 @@ interface LocaleRefreshResult {
     refreshed: string[];
     versions: Record<string, string>;
 }
+/**
+ * Flat error-message catalog for a single language: backend error code → sentence.
+ *
+ * Keys are the `extensions.code` values the backend returns on a rejection
+ * (`Bid_RateLimited`, `Wallet_WithdrawNetworkUnavailable`, …). Values may contain
+ * `{name}` placeholders filled from the error's meta at lookup time.
+ */
+type ErrorMessageCatalog = Record<string, string>;
+/**
+ * Values available to fill a catalog row's `{name}` placeholders — normally the
+ * `meta` carried by the backend error. Values are stringified as-is; a caller who
+ * needs specific formatting (decimal places, currency) should format before passing.
+ */
+type ErrorMessageMeta = Record<string, unknown>;
+/**
+ * Public response shape from LocaleModule.getErrorMessages().
+ *
+ * Mirrors {@link LocaleResponse}, with one wire-level difference: `messages`
+ * arrives as a real JSON object rather than a JSON-string, so there is no parse
+ * step. Non-string values are dropped during normalisation.
+ *
+ * `messages` is null when `notModified` is true (caller keeps prior state).
+ */
+interface ErrorMessagesResponse {
+    lang: string;
+    version: string;
+    notModified: boolean;
+    messages: ErrorMessageCatalog | null;
+}
+
+/**
+ * Pure helpers behind the error-message catalog.
+ *
+ * Kept free of I/O and of module state so the precedence rule, the language
+ * mapping and the template filling are all testable without a transport.
+ */
+
+/**
+ * Reduce a host language tag to the catalog's column name.
+ *
+ * The sheet's columns are en, vi, es, hi, zh-TW, zh-CN, ja, pt, fr, de, it, tr,
+ * ko, ar. Only Chinese needs more than the primary subtag: zh-TW and zh-CN are
+ * different SCRIPTS, so collapsing both to "zh" would show Simplified text to a
+ * Traditional reader. Everything else drops its region.
+ *
+ * The supported-language list is deliberately NOT duplicated here — the server
+ * owns it, and an unsupported tag simply fails the fetch and leaves prior copy
+ * in place, which is the same outcome a stale local list would produce with
+ * more code.
+ */
+declare function normaliseLang(tag: string): string;
 
 interface LocaleModuleDeps {
     graphql: GraphQLTransport;
@@ -484,6 +535,66 @@ declare class LocaleModule {
     get(lang: string, knownVersion?: string, opts?: {
         signal?: AbortSignal;
     }): Promise<LocaleResponse>;
+    /**
+     * Fetch the error-message catalog for a single language.
+     *
+     * The throwing sibling of {@link loadErrorMessages}: errors surface as
+     * TaphubError subclasses with backend `extensions.code` values
+     * (`LangNotSupported`, `FeatureDisabled`, …), because a caller doing an
+     * explicit fetch wants to see why it failed. Hosts that just want copy on
+     * screen should call `loadErrorMessages` instead.
+     *
+     * `lang` is passed through as given — normalisation is `loadErrorMessages`'
+     * job, so an explicit caller keeps full control of the tag.
+     */
+    getErrorMessages(lang: string, knownVersion?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ErrorMessagesResponse>;
+    /**
+     * Load the error-message catalog for `lang` into this client.
+     *
+     * Background hydration with nobody waiting on it, so it **never throws and
+     * never rejects**. Every failure path — network error, backend down,
+     * `FeatureDisabled` when the source sheet is not configured, an unsupported
+     * tag, a malformed body — leaves the previously loaded catalog in place.
+     * Failing to translate an error must not itself become an error.
+     *
+     * The tag is normalised first (region dropped, Chinese scripts kept apart),
+     * so a host can hand over `navigator.language` untouched.
+     *
+     * Concurrent calls for the same language share one request. The catalog lives
+     * on the client while the thing that triggers a load (a mounted provider)
+     * lives a level below, so two providers sharing one client would otherwise
+     * fetch the same bytes into the same place twice.
+     *
+     * This is dedup, not caching — it lasts only while a request is in flight. A
+     * host calling again after one settles gets a fresh fetch.
+     *
+     * Deliberately takes NO AbortSignal. A follower piggybacking on someone
+     * else's request would otherwise have its outcome decided by whether that
+     * other caller happened to unmount first. Letting a background hydration run
+     * to completion costs one small request; stranding a caller costs all the
+     * error copy on screen.
+     *
+     * No persistence and no polling: the host decides when to call this. The
+     * React provider calls it on mount and on language change.
+     */
+    loadErrorMessages(lang: string): Promise<void>;
+    /**
+     * The sentence to show for a backend error `code`.
+     *
+     * **Synchronous by design** — error copy is read when a toast is built, inside
+     * a `catch` or an error handler, where React hooks are illegal. That is why
+     * this is a plain method and not a hook.
+     *
+     * Returns `fallback` whenever the catalog cannot produce a usable sentence: no
+     * catalog loaded yet, no row for the code, or a blank row. Never returns an
+     * empty string, and never returns the raw code.
+     *
+     * `meta` fills `{name}` placeholders in a catalog row; any placeholder left
+     * unfilled is stripped, so raw braces never reach the user.
+     */
+    errorMessage(code: string, fallback: string, meta?: ErrorMessageMeta): string;
     /**
      * Trigger an admin refresh — backend re-pulls the source Sheet, invalidates
      * its cache, and writes fresh entries for every supported language.
@@ -598,6 +709,13 @@ interface PairInfo {
      */
     agencyPairId: string | null;
 }
+/**
+ * Default number of candles fetched on initial chart load when the caller does
+ * not pass an explicit limit. The server clamps any request to its cache size
+ * (grid-api services.ChartHistoryMaxLimit = 1500), so this is purely how much
+ * history the chart shows by default — kept lower than the cap for faster init.
+ */
+declare const DEFAULT_CHART_HISTORY_LIMIT = 600;
 interface Candle {
     /** Unix epoch SECONDS (not ms). Multiply by 1000 for JS Date. */
     time: number;
@@ -795,6 +913,16 @@ interface MqttTransport {
     close(): void;
 }
 
+/**
+ * Candle tick kind. `new` = a fresh bar opened; `update` = the current bar was
+ * revised. Exported as named constants so consumers compare against these
+ * instead of bare string literals (a typo on a literal fails silently).
+ */
+declare const CANDLE_EVENT: {
+    readonly NEW: "new";
+    readonly UPDATE: "update";
+};
+type CandleEventType = (typeof CANDLE_EVENT)[keyof typeof CANDLE_EVENT];
 /**
  * Candle tick from MQTT.
  * WARNING: `time` is Unix epoch MILLISECONDS.
@@ -802,7 +930,7 @@ interface MqttTransport {
  * Do NOT multiply MQTT candle time by 1000.
  */
 interface MqttCandleEvent {
-    type: 'new' | 'update';
+    type: CandleEventType;
     /** Unix epoch **milliseconds** — differs from GQL chartHistory (seconds) */
     time: number;
     o: number;
@@ -1304,4 +1432,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, pairIdFromBidResultTopic };
+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 };

package/dist/index.js

@@ -715,6 +715,39 @@ var LeaderboardModule = class {
   }
 };
 
+// src/modules/locale/errorMessages.ts
+function normaliseLang(tag) {
+  const clean = (tag || "").trim().toLowerCase();
+  if (!clean) return "en";
+  if (clean === "zh" || clean.startsWith("zh-")) {
+    if (/(^|-)(hant|tw|hk|mo)(-|$)/.test(clean)) return "zh-TW";
+    return "zh-CN";
+  }
+  return clean.split("-")[0] || "en";
+}
+function pickStringEntries(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") out[key] = entry;
+  }
+  return out;
+}
+function interpolate(template, meta) {
+  const filled = template.replace(/\{(\w+)\}/g, (_match, key) => {
+    const value = meta?.[key];
+    if (value === void 0 || value === null) return "";
+    return String(value);
+  });
+  return filled.replace(/\s{2,}/g, " ").trim();
+}
+function resolveErrorMessage(code, catalog, fallback, meta) {
+  const row = catalog?.[code];
+  if (typeof row !== "string" || row.trim() === "") return fallback;
+  const filled = interpolate(row, meta);
+  return filled === "" ? fallback : filled;
+}
+
 // src/modules/locale/normalise.ts
 function normaliseLocaleResponse(node) {
   let translations = null;
@@ -739,6 +772,14 @@ function normaliseLocaleResponse(node) {
     translations
   };
 }
+function normaliseErrorMessagesResponse(node) {
+  return {
+    lang: node.lang,
+    version: node.version,
+    notModified: node.notModified,
+    messages: node.messages === null ? null : pickStringEntries(node.messages)
+  };
+}
 function normaliseRefreshLocalesPayload(node) {
   let versions;
   try {
@@ -772,10 +813,33 @@ var REFRESH_LOCALES_MUTATION = `mutation RefreshLocales {
     versions
   }
 }`;
+var ERROR_MESSAGES_QUERY = `query ErrorMessages($input: LocalesInput!) {
+  errorMessages(input: $input) {
+    lang
+    version
+    notModified
+    messages
+  }
+}`;
 
 // src/modules/locale/index.ts
 var LocaleModule = class {
   #graphql;
+  /**
+   * The loaded error-message catalog. Instance state, not module state, so two
+   * clients in one process (tests, multi-tenant hosts) never share a catalog.
+   *
+   * Null until a load succeeds. It is NEVER reset to null afterwards — a failed
+   * refresh keeps the last-known-good copy, because losing all error copy is
+   * strictly worse than showing slightly stale copy.
+   */
+  #errorMessages = null;
+  /**
+   * In-flight catalog loads, keyed by normalised language. Collapses concurrent
+   * callers onto one request; entries are removed as soon as a load settles, so
+   * this never becomes a cache of results (or of failures).
+   */
+  #errorMessagesInFlight = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
@@ -798,6 +862,94 @@ var LocaleModule = class {
     const body = await this.#graphql.request(LOCALES_QUERY, { input }, opts);
     return normaliseLocaleResponse(body.locales);
   }
+  /**
+   * Fetch the error-message catalog for a single language.
+   *
+   * The throwing sibling of {@link loadErrorMessages}: errors surface as
+   * TaphubError subclasses with backend `extensions.code` values
+   * (`LangNotSupported`, `FeatureDisabled`, …), because a caller doing an
+   * explicit fetch wants to see why it failed. Hosts that just want copy on
+   * screen should call `loadErrorMessages` instead.
+   *
+   * `lang` is passed through as given — normalisation is `loadErrorMessages`'
+   * job, so an explicit caller keeps full control of the tag.
+   */
+  async getErrorMessages(lang, knownVersion, opts) {
+    const input = { lang };
+    if (knownVersion !== void 0 && knownVersion !== "") {
+      input.knownVersion = knownVersion;
+    }
+    const body = await this.#graphql.request(
+      ERROR_MESSAGES_QUERY,
+      { input },
+      opts
+    );
+    return normaliseErrorMessagesResponse(body.errorMessages);
+  }
+  /**
+   * Load the error-message catalog for `lang` into this client.
+   *
+   * Background hydration with nobody waiting on it, so it **never throws and
+   * never rejects**. Every failure path — network error, backend down,
+   * `FeatureDisabled` when the source sheet is not configured, an unsupported
+   * tag, a malformed body — leaves the previously loaded catalog in place.
+   * Failing to translate an error must not itself become an error.
+   *
+   * The tag is normalised first (region dropped, Chinese scripts kept apart),
+   * so a host can hand over `navigator.language` untouched.
+   *
+   * Concurrent calls for the same language share one request. The catalog lives
+   * on the client while the thing that triggers a load (a mounted provider)
+   * lives a level below, so two providers sharing one client would otherwise
+   * fetch the same bytes into the same place twice.
+   *
+   * This is dedup, not caching — it lasts only while a request is in flight. A
+   * host calling again after one settles gets a fresh fetch.
+   *
+   * Deliberately takes NO AbortSignal. A follower piggybacking on someone
+   * else's request would otherwise have its outcome decided by whether that
+   * other caller happened to unmount first. Letting a background hydration run
+   * to completion costs one small request; stranding a caller costs all the
+   * error copy on screen.
+   *
+   * No persistence and no polling: the host decides when to call this. The
+   * React provider calls it on mount and on language change.
+   */
+  async loadErrorMessages(lang) {
+    const key = normaliseLang(lang);
+    const inFlight = this.#errorMessagesInFlight.get(key);
+    if (inFlight) return inFlight;
+    const run = (async () => {
+      try {
+        const res = await this.getErrorMessages(key);
+        if (res.notModified || res.messages === null) return;
+        if (Object.keys(res.messages).length === 0) return;
+        this.#errorMessages = res.messages;
+      } catch {
+      } finally {
+        this.#errorMessagesInFlight.delete(key);
+      }
+    })();
+    this.#errorMessagesInFlight.set(key, run);
+    return run;
+  }
+  /**
+   * The sentence to show for a backend error `code`.
+   *
+   * **Synchronous by design** — error copy is read when a toast is built, inside
+   * a `catch` or an error handler, where React hooks are illegal. That is why
+   * this is a plain method and not a hook.
+   *
+   * Returns `fallback` whenever the catalog cannot produce a usable sentence: no
+   * catalog loaded yet, no row for the code, or a blank row. Never returns an
+   * empty string, and never returns the raw code.
+   *
+   * `meta` fills `{name}` placeholders in a catalog row; any placeholder left
+   * unfilled is stripped, so raw braces never reach the user.
+   */
+  errorMessage(code, fallback, meta) {
+    return resolveErrorMessage(code, this.#errorMessages, fallback, meta);
+  }
   /**
    * Trigger an admin refresh — backend re-pulls the source Sheet, invalidates
    * its cache, and writes fresh entries for every supported language.
@@ -928,6 +1080,9 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
   }
 }`;
 
+// src/modules/pair/types.ts
+var DEFAULT_CHART_HISTORY_LIMIT = 600;
+
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
@@ -985,11 +1140,8 @@ var PairModule = class {
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
   // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
-  async chartHistory(pairId, limit, opts) {
-    const variables = { pairId };
-    if (limit !== void 0) {
-      variables.limit = limit;
-    }
+  async chartHistory(pairId, limit = DEFAULT_CHART_HISTORY_LIMIT, opts) {
+    const variables = { pairId, limit };
     const body = await this.#graphql.request(
       CHART_HISTORY_QUERY,
       variables,
@@ -2940,6 +3092,12 @@ var TaphubClient = class {
   }
 };
 
+// src/modules/realtime/types.ts
+var CANDLE_EVENT = {
+  NEW: "new",
+  UPDATE: "update"
+};
+
 // src/utils/coefficient.ts
 function errorFunction(x) {
   const a1 = 0.254829592;
@@ -3028,6 +3186,8 @@ export {
   AgencyPairModule,
   AuthModule,
   BidModule,
+  CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule,
   LocaleModule,
   NetworkQualityMonitor,
@@ -3055,5 +3215,6 @@ export {
   isWin,
   normalCDF,
   normalPDF,
+  normaliseLang,
   pairIdFromBidResultTopic
 };

package/package.json

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