@taphubhq/sdk-core 0.24.0 → 0.24.2

package/dist/index.cjs

@@ -64,6 +64,35 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/clock/ClockSync.ts
+var ClockSync = class {
+  #offsetMs = 0;
+  #synced = false;
+  /** True once an offset has been recorded. */
+  get synced() {
+    return this.#synced;
+  }
+  /**
+   * Milliseconds to add to the client clock to reach the server clock.
+   * Returns 0 until the first successful sync.
+   */
+  getOffset() {
+    return this.#offsetMs;
+  }
+  /**
+   * Record a single clock sample from a round-trip that returned the server time.
+   * No-op if already synced (set-once), or if any input is not a finite number — a
+   * missing/garbage `serverTime` must never corrupt the offset.
+   */
+  recordSync(sample) {
+    if (this.#synced) return;
+    const { t0, serverTime, t1 } = sample;
+    if (!Number.isFinite(t0) || !Number.isFinite(serverTime) || !Number.isFinite(t1)) return;
+    this.#offsetMs = Math.round(serverTime + (t1 - t0) / 2 - t1);
+    this.#synced = true;
+  }
+};
+
 // src/errors/index.ts
 var TaphubError = class _TaphubError extends Error {
   code;
@@ -518,8 +547,10 @@ var isCancelled = (bid) => bid.status === "cancelled";
 // src/modules/bid/index.ts
 var BidModule = class {
   #graphql;
+  #getClockOffset;
   constructor(deps) {
     this.#graphql = deps.graphql;
+    this.#getClockOffset = deps.getClockOffset;
   }
   async placeBid(input, opts) {
     const variables = {
@@ -537,6 +568,12 @@ var BidModule = class {
         coefficient: input.coefficient,
         amount: input.amount,
         slippage: input.slippage,
+        // bid-260619-client-time-meta: auto-stamp the client's RAW send time and the
+        // measured clock offset so the server can record skew-corrected latency into
+        // bid.meta. Stamped here at dispatch (not caller-supplied) so `ct` is the actual
+        // send moment. The server treats both as untrusted tracing data only.
+        ct: Date.now(),
+        clockOffset: this.#getClockOffset(),
         // QA-only late-bid passthrough (bid-260610). Omitted entirely when absent
         // so no `bidToken: null` is sent. sdk-react sets it from localStorage.
         ...input.bidToken ? { bidToken: input.bidToken } : {}
@@ -930,6 +967,7 @@ function normalisePairInfo(node) {
 
 // src/modules/pair/queries.ts
 var PAIR_QUERY = `query AgencyPair($pairId: ID!) {
+  serverTime
   agencyPair(pairId: $pairId) {
     id pair { id pair source thumb } status createdAt
     config {
@@ -959,8 +997,10 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
+  #clockSync;
   constructor(deps) {
     this.#graphql = deps.graphql;
+    this.#clockSync = deps.clockSync;
   }
   // REVIEW[bid-260602-v2]: keyed by pairId (the #2 game_pairs.id, e.g. "grid-ETH-USD").
   // Dropped the `pair` symbol arg + `gameplaySlug` option — the gameplay is already
@@ -968,6 +1008,7 @@ var PairModule = class {
   async get(pairId, opts) {
     const variables = { pairId };
     let body;
+    const t0 = Date.now();
     try {
       body = await this.#graphql.request(PAIR_QUERY, variables, opts);
     } catch (err) {
@@ -979,6 +1020,7 @@ var PairModule = class {
       }
       throw err;
     }
+    this.#clockSync.recordSync({ t0, serverTime: body.serverTime, t1: Date.now() });
     if (body.agencyPair === null) {
       throw new TaphubValidationError("Game not found for pair", {
         code: "GameNotFound",
@@ -1983,20 +2025,9 @@ function classifyNetworkLevel(rtt) {
 // src/network/RttSmoother.ts
 var EMA_ALPHA = 0.25;
 var OUTLIER_MULTIPLIER = 3;
-var DEBOUNCE_DEGRADE = 2;
-var DEBOUNCE_IMPROVE = 5;
-var LEVEL_RANK = {
-  good: 0,
-  fair: 1,
-  poor: 2,
-  offline: 3
-};
 var RttSmoother = class {
   ema = 0;
   level = "good";
-  committed = "good";
-  candidate = "good";
-  candidateCount = 0;
   overrideOffline = false;
   consecutiveOutliers = 0;
   add(rtt) {
@@ -2008,23 +2039,7 @@ var RttSmoother = class {
     }
     const coldStart = this.ema === 0;
     this.ema = coldStart ? rtt : EMA_ALPHA * rtt + (1 - EMA_ALPHA) * this.ema;
-    const next = classifyNetworkLevel(this.ema);
-    if (coldStart) {
-      this.committed = next;
-      this.candidate = next;
-      this.candidateCount = 1;
-    } else {
-      if (next === this.candidate) {
-        this.candidateCount += 1;
-      } else {
-        this.candidate = next;
-        this.candidateCount = 1;
-      }
-      if (this.candidateCount >= this.requiredSamplesFor(next)) {
-        this.committed = next;
-      }
-    }
-    this.level = this.overrideOffline ? "offline" : this.committed;
+    this.level = this.overrideOffline ? "offline" : classifyNetworkLevel(this.ema);
   }
   forceOffline() {
     this.overrideOffline = true;
@@ -2032,20 +2047,14 @@ var RttSmoother = class {
   }
   releaseOffline() {
     this.overrideOffline = false;
-    this.level = this.committed;
+    this.level = classifyNetworkLevel(this.ema);
   }
   reset() {
     this.ema = 0;
-    this.committed = "good";
-    this.candidate = "good";
-    this.candidateCount = 0;
     this.consecutiveOutliers = 0;
     this.overrideOffline = false;
     this.level = "good";
   }
-  requiredSamplesFor(next) {
-    return LEVEL_RANK[next] > LEVEL_RANK[this.committed] ? DEBOUNCE_DEGRADE : DEBOUNCE_IMPROVE;
-  }
 };
 
 // src/network/NetworkQualityMonitor.ts
@@ -2072,7 +2081,6 @@ var NetworkQualityMonitor = class {
   smoother = new RttSmoother();
   mqttConnected = false;
   mqttDisconnectedAt = null;
-  committedNetwork = "good";
   committedBackend = "ok";
   // The last snapshot we emitted, used to decide whether the next recompute is
   // worth emitting. Seeded with the initial default so the first real change
@@ -2150,7 +2158,6 @@ var NetworkQualityMonitor = class {
     this.smoother.reset();
     this.mqttConnected = false;
     this.mqttDisconnectedAt = null;
-    this.committedNetwork = "good";
     this.committedBackend = "ok";
     this.emitIfChanged(this.snapshot());
   }
@@ -2214,26 +2221,12 @@ var NetworkQualityMonitor = class {
     const useConnection = realSamples.length < COLD_START_REAL_SAMPLE_THRESHOLD;
     const effectiveSamples = useConnection ? allSamples : realSamples;
     const httpSamples = effectiveSamples.filter((s) => isHttpSource(s.source));
-    const backend = classifyBackendHealth(httpSamples);
-    const metrics = this.deriveMetricsFrom(effectiveSamples);
-    const candidate = classifyNetworkLevel(metrics.emaForLevel);
-    let nextNetwork = this.smoother.level;
-    if (effectiveSamples.length === 0) {
-      nextNetwork = this.committedNetwork;
-    } else if (this.smoother.ema > 0) {
-      nextNetwork = this.smoother.level;
-    } else {
-      nextNetwork = candidate;
-    }
+    this.committedBackend = classifyBackendHealth(httpSamples);
     if (this.isHardOffline()) {
       this.smoother.forceOffline();
-      nextNetwork = "offline";
     } else if (this.smoother.level === "offline") {
       this.smoother.releaseOffline();
-      nextNetwork = this.smoother.level;
     }
-    this.committedNetwork = nextNetwork;
-    this.committedBackend = backend;
     this.emitIfChanged(this.snapshot());
   }
   // Emits network:change when any *displayed* field of the snapshot moves. This
@@ -2294,10 +2287,12 @@ var NetworkQualityMonitor = class {
   snapshot() {
     const samples = this.allHttpAndMqttSamples();
     const metrics = this.deriveMetricsFrom(samples);
+    const rtt = Math.round(metrics.emaForLevel);
+    const network = this.smoother.level === "offline" ? "offline" : classifyNetworkLevel(rtt);
     return {
-      network: this.committedNetwork,
+      network,
       backend: this.committedBackend,
-      rtt: Math.round(metrics.emaForLevel),
+      rtt,
       jitter: Math.round(metrics.jitter),
       lossRate: metrics.lossRate,
       mqttConnected: this.mqttConnected,
@@ -2905,8 +2900,12 @@ var TaphubClient = class {
         this.user.clearCurrencies();
       }
     });
-    this.pair = new PairModule({ graphql: this.#graphql });
-    this.bid = new BidModule({ graphql: this.#graphql });
+    const clockSync = new ClockSync();
+    this.pair = new PairModule({ graphql: this.#graphql, clockSync });
+    this.bid = new BidModule({
+      graphql: this.#graphql,
+      getClockOffset: () => clockSync.getOffset()
+    });
     this.leaderboard = new LeaderboardModule({ graphql: this.#graphql });
     this.agencyPairs = new AgencyPairModule({ graphql: this.#graphql });
     this.locale = new LocaleModule({ graphql: this.#graphql });

package/dist/index.d.mts

@@ -270,6 +270,7 @@ declare const isCancelled: (bid: Bid) => boolean;
 
 interface BidModuleDeps {
     graphql: GraphQLTransport;
+    getClockOffset: () => number;
 }
 declare class BidModule {
     #private;
@@ -496,6 +497,44 @@ declare class LocaleModule {
     }): Promise<LocaleRefreshResult>;
 }
 
+/**
+ * ClockSync estimates the offset between the client clock and the server clock, so that
+ * timestamps the client reports (e.g. a bid's send time) can be expressed on the server's
+ * timeline and latency measurements are not distorted by client clock skew.
+ *
+ * The offset is measured ONCE per session (set-once) from a single round-trip whose
+ * response carries the server time, using Cristian's algorithm:
+ *
+ *     offset = serverTime + (t1 - t0) / 2 - t1
+ *
+ * where `t0` / `t1` are the client clock immediately before / after the request. `offset`
+ * is the number of milliseconds to ADD to the client clock to obtain the server clock.
+ *
+ * This is adequate for millisecond-grade latency tracing (the `bid-260619-server-time-sync`
+ * capability); it is intentionally NOT a high-precision NTP implementation, and it does not
+ * re-sync to correct drift.
+ */
+declare class ClockSync {
+    #private;
+    /** True once an offset has been recorded. */
+    get synced(): boolean;
+    /**
+     * Milliseconds to add to the client clock to reach the server clock.
+     * Returns 0 until the first successful sync.
+     */
+    getOffset(): number;
+    /**
+     * Record a single clock sample from a round-trip that returned the server time.
+     * No-op if already synced (set-once), or if any input is not a finite number — a
+     * missing/garbage `serverTime` must never corrupt the offset.
+     */
+    recordSync(sample: {
+        t0: number;
+        serverTime: number;
+        t1: number;
+    }): void;
+}
+
 interface Pair {
     id: string;
     pair: string;
@@ -572,6 +611,7 @@ interface Candle {
 
 interface PairModuleDeps {
     graphql: GraphQLTransport;
+    clockSync: ClockSync;
 }
 declare class PairModule {
     #private;
@@ -1099,7 +1139,6 @@ declare class NetworkQualityMonitor {
     private readonly smoother;
     private mqttConnected;
     private mqttDisconnectedAt;
-    private committedNetwork;
     private committedBackend;
     private lastEmitted;
     private tickHandle;

package/dist/index.d.ts

@@ -270,6 +270,7 @@ declare const isCancelled: (bid: Bid) => boolean;
 
 interface BidModuleDeps {
     graphql: GraphQLTransport;
+    getClockOffset: () => number;
 }
 declare class BidModule {
     #private;
@@ -496,6 +497,44 @@ declare class LocaleModule {
     }): Promise<LocaleRefreshResult>;
 }
 
+/**
+ * ClockSync estimates the offset between the client clock and the server clock, so that
+ * timestamps the client reports (e.g. a bid's send time) can be expressed on the server's
+ * timeline and latency measurements are not distorted by client clock skew.
+ *
+ * The offset is measured ONCE per session (set-once) from a single round-trip whose
+ * response carries the server time, using Cristian's algorithm:
+ *
+ *     offset = serverTime + (t1 - t0) / 2 - t1
+ *
+ * where `t0` / `t1` are the client clock immediately before / after the request. `offset`
+ * is the number of milliseconds to ADD to the client clock to obtain the server clock.
+ *
+ * This is adequate for millisecond-grade latency tracing (the `bid-260619-server-time-sync`
+ * capability); it is intentionally NOT a high-precision NTP implementation, and it does not
+ * re-sync to correct drift.
+ */
+declare class ClockSync {
+    #private;
+    /** True once an offset has been recorded. */
+    get synced(): boolean;
+    /**
+     * Milliseconds to add to the client clock to reach the server clock.
+     * Returns 0 until the first successful sync.
+     */
+    getOffset(): number;
+    /**
+     * Record a single clock sample from a round-trip that returned the server time.
+     * No-op if already synced (set-once), or if any input is not a finite number — a
+     * missing/garbage `serverTime` must never corrupt the offset.
+     */
+    recordSync(sample: {
+        t0: number;
+        serverTime: number;
+        t1: number;
+    }): void;
+}
+
 interface Pair {
     id: string;
     pair: string;
@@ -572,6 +611,7 @@ interface Candle {
 
 interface PairModuleDeps {
     graphql: GraphQLTransport;
+    clockSync: ClockSync;
 }
 declare class PairModule {
     #private;
@@ -1099,7 +1139,6 @@ declare class NetworkQualityMonitor {
     private readonly smoother;
     private mqttConnected;
     private mqttDisconnectedAt;
-    private committedNetwork;
     private committedBackend;
     private lastEmitted;
     private tickHandle;

package/dist/index.js

@@ -1,3 +1,32 @@
+// src/clock/ClockSync.ts
+var ClockSync = class {
+  #offsetMs = 0;
+  #synced = false;
+  /** True once an offset has been recorded. */
+  get synced() {
+    return this.#synced;
+  }
+  /**
+   * Milliseconds to add to the client clock to reach the server clock.
+   * Returns 0 until the first successful sync.
+   */
+  getOffset() {
+    return this.#offsetMs;
+  }
+  /**
+   * Record a single clock sample from a round-trip that returned the server time.
+   * No-op if already synced (set-once), or if any input is not a finite number — a
+   * missing/garbage `serverTime` must never corrupt the offset.
+   */
+  recordSync(sample) {
+    if (this.#synced) return;
+    const { t0, serverTime, t1 } = sample;
+    if (!Number.isFinite(t0) || !Number.isFinite(serverTime) || !Number.isFinite(t1)) return;
+    this.#offsetMs = Math.round(serverTime + (t1 - t0) / 2 - t1);
+    this.#synced = true;
+  }
+};
+
 // src/errors/index.ts
 var TaphubError = class _TaphubError extends Error {
   code;
@@ -452,8 +481,10 @@ var isCancelled = (bid) => bid.status === "cancelled";
 // src/modules/bid/index.ts
 var BidModule = class {
   #graphql;
+  #getClockOffset;
   constructor(deps) {
     this.#graphql = deps.graphql;
+    this.#getClockOffset = deps.getClockOffset;
   }
   async placeBid(input, opts) {
     const variables = {
@@ -471,6 +502,12 @@ var BidModule = class {
         coefficient: input.coefficient,
         amount: input.amount,
         slippage: input.slippage,
+        // bid-260619-client-time-meta: auto-stamp the client's RAW send time and the
+        // measured clock offset so the server can record skew-corrected latency into
+        // bid.meta. Stamped here at dispatch (not caller-supplied) so `ct` is the actual
+        // send moment. The server treats both as untrusted tracing data only.
+        ct: Date.now(),
+        clockOffset: this.#getClockOffset(),
         // QA-only late-bid passthrough (bid-260610). Omitted entirely when absent
         // so no `bidToken: null` is sent. sdk-react sets it from localStorage.
         ...input.bidToken ? { bidToken: input.bidToken } : {}
@@ -864,6 +901,7 @@ function normalisePairInfo(node) {
 
 // src/modules/pair/queries.ts
 var PAIR_QUERY = `query AgencyPair($pairId: ID!) {
+  serverTime
   agencyPair(pairId: $pairId) {
     id pair { id pair source thumb } status createdAt
     config {
@@ -893,8 +931,10 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
+  #clockSync;
   constructor(deps) {
     this.#graphql = deps.graphql;
+    this.#clockSync = deps.clockSync;
   }
   // REVIEW[bid-260602-v2]: keyed by pairId (the #2 game_pairs.id, e.g. "grid-ETH-USD").
   // Dropped the `pair` symbol arg + `gameplaySlug` option — the gameplay is already
@@ -902,6 +942,7 @@ var PairModule = class {
   async get(pairId, opts) {
     const variables = { pairId };
     let body;
+    const t0 = Date.now();
     try {
       body = await this.#graphql.request(PAIR_QUERY, variables, opts);
     } catch (err) {
@@ -913,6 +954,7 @@ var PairModule = class {
       }
       throw err;
     }
+    this.#clockSync.recordSync({ t0, serverTime: body.serverTime, t1: Date.now() });
     if (body.agencyPair === null) {
       throw new TaphubValidationError("Game not found for pair", {
         code: "GameNotFound",
@@ -1917,20 +1959,9 @@ function classifyNetworkLevel(rtt) {
 // src/network/RttSmoother.ts
 var EMA_ALPHA = 0.25;
 var OUTLIER_MULTIPLIER = 3;
-var DEBOUNCE_DEGRADE = 2;
-var DEBOUNCE_IMPROVE = 5;
-var LEVEL_RANK = {
-  good: 0,
-  fair: 1,
-  poor: 2,
-  offline: 3
-};
 var RttSmoother = class {
   ema = 0;
   level = "good";
-  committed = "good";
-  candidate = "good";
-  candidateCount = 0;
   overrideOffline = false;
   consecutiveOutliers = 0;
   add(rtt) {
@@ -1942,23 +1973,7 @@ var RttSmoother = class {
     }
     const coldStart = this.ema === 0;
     this.ema = coldStart ? rtt : EMA_ALPHA * rtt + (1 - EMA_ALPHA) * this.ema;
-    const next = classifyNetworkLevel(this.ema);
-    if (coldStart) {
-      this.committed = next;
-      this.candidate = next;
-      this.candidateCount = 1;
-    } else {
-      if (next === this.candidate) {
-        this.candidateCount += 1;
-      } else {
-        this.candidate = next;
-        this.candidateCount = 1;
-      }
-      if (this.candidateCount >= this.requiredSamplesFor(next)) {
-        this.committed = next;
-      }
-    }
-    this.level = this.overrideOffline ? "offline" : this.committed;
+    this.level = this.overrideOffline ? "offline" : classifyNetworkLevel(this.ema);
   }
   forceOffline() {
     this.overrideOffline = true;
@@ -1966,20 +1981,14 @@ var RttSmoother = class {
   }
   releaseOffline() {
     this.overrideOffline = false;
-    this.level = this.committed;
+    this.level = classifyNetworkLevel(this.ema);
   }
   reset() {
     this.ema = 0;
-    this.committed = "good";
-    this.candidate = "good";
-    this.candidateCount = 0;
     this.consecutiveOutliers = 0;
     this.overrideOffline = false;
     this.level = "good";
   }
-  requiredSamplesFor(next) {
-    return LEVEL_RANK[next] > LEVEL_RANK[this.committed] ? DEBOUNCE_DEGRADE : DEBOUNCE_IMPROVE;
-  }
 };
 
 // src/network/NetworkQualityMonitor.ts
@@ -2006,7 +2015,6 @@ var NetworkQualityMonitor = class {
   smoother = new RttSmoother();
   mqttConnected = false;
   mqttDisconnectedAt = null;
-  committedNetwork = "good";
   committedBackend = "ok";
   // The last snapshot we emitted, used to decide whether the next recompute is
   // worth emitting. Seeded with the initial default so the first real change
@@ -2084,7 +2092,6 @@ var NetworkQualityMonitor = class {
     this.smoother.reset();
     this.mqttConnected = false;
     this.mqttDisconnectedAt = null;
-    this.committedNetwork = "good";
     this.committedBackend = "ok";
     this.emitIfChanged(this.snapshot());
   }
@@ -2148,26 +2155,12 @@ var NetworkQualityMonitor = class {
     const useConnection = realSamples.length < COLD_START_REAL_SAMPLE_THRESHOLD;
     const effectiveSamples = useConnection ? allSamples : realSamples;
     const httpSamples = effectiveSamples.filter((s) => isHttpSource(s.source));
-    const backend = classifyBackendHealth(httpSamples);
-    const metrics = this.deriveMetricsFrom(effectiveSamples);
-    const candidate = classifyNetworkLevel(metrics.emaForLevel);
-    let nextNetwork = this.smoother.level;
-    if (effectiveSamples.length === 0) {
-      nextNetwork = this.committedNetwork;
-    } else if (this.smoother.ema > 0) {
-      nextNetwork = this.smoother.level;
-    } else {
-      nextNetwork = candidate;
-    }
+    this.committedBackend = classifyBackendHealth(httpSamples);
     if (this.isHardOffline()) {
       this.smoother.forceOffline();
-      nextNetwork = "offline";
     } else if (this.smoother.level === "offline") {
       this.smoother.releaseOffline();
-      nextNetwork = this.smoother.level;
     }
-    this.committedNetwork = nextNetwork;
-    this.committedBackend = backend;
     this.emitIfChanged(this.snapshot());
   }
   // Emits network:change when any *displayed* field of the snapshot moves. This
@@ -2228,10 +2221,12 @@ var NetworkQualityMonitor = class {
   snapshot() {
     const samples = this.allHttpAndMqttSamples();
     const metrics = this.deriveMetricsFrom(samples);
+    const rtt = Math.round(metrics.emaForLevel);
+    const network = this.smoother.level === "offline" ? "offline" : classifyNetworkLevel(rtt);
     return {
-      network: this.committedNetwork,
+      network,
       backend: this.committedBackend,
-      rtt: Math.round(metrics.emaForLevel),
+      rtt,
       jitter: Math.round(metrics.jitter),
       lossRate: metrics.lossRate,
       mqttConnected: this.mqttConnected,
@@ -2839,8 +2834,12 @@ var TaphubClient = class {
         this.user.clearCurrencies();
       }
     });
-    this.pair = new PairModule({ graphql: this.#graphql });
-    this.bid = new BidModule({ graphql: this.#graphql });
+    const clockSync = new ClockSync();
+    this.pair = new PairModule({ graphql: this.#graphql, clockSync });
+    this.bid = new BidModule({
+      graphql: this.#graphql,
+      getClockOffset: () => clockSync.getOffset()
+    });
     this.leaderboard = new LeaderboardModule({ graphql: this.#graphql });
     this.agencyPairs = new AgencyPairModule({ graphql: this.#graphql });
     this.locale = new LocaleModule({ graphql: this.#graphql });

package/package.json

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