@taphubhq/sdk-core 0.25.3 → 0.25.4

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   isWin: () => isWin,
   normalCDF: () => normalCDF,
   normalPDF: () => normalPDF,
+  normaliseLang: () => normaliseLang,
   pairIdFromBidResultTopic: () => pairIdFromBidResultTopic
 });
 module.exports = __toCommonJS(index_exports);
@@ -781,6 +782,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 +839,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 +880,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 +929,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.
@@ -3122,5 +3275,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.
@@ -1304,4 +1415,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, type CancelBidResult, type Candle, type Constraints, type Currency, 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.
@@ -1304,4 +1415,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, type CancelBidResult, type Candle, type Constraints, type Currency, 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.
@@ -3055,5 +3207,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.4",
   "description": "Core SDK for building on the TabHub platform",
   "license": "MIT",
   "main": "./dist/index.cjs",