@taphubhq/sdk-core 0.24.1 → 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",
@@ -2858,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;

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;

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",
@@ -2792,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.1",
+  "version": "0.24.2",
   "description": "Core SDK for building on the TabHub platform",
   "license": "MIT",
   "main": "./dist/index.cjs",