@hypersoniclabs/helix-sdk 0.1.1 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +954 -2
  2. package/dist/action-surface.d.ts +182 -0
  3. package/dist/action-surface.js +1032 -0
  4. package/dist/action-surface.js.map +1 -0
  5. package/dist/camera.d.ts +78 -0
  6. package/dist/camera.js +640 -0
  7. package/dist/camera.js.map +1 -0
  8. package/dist/dev-shell/criteria.d.ts +46 -0
  9. package/dist/dev-shell/criteria.js +98 -0
  10. package/dist/dev-shell/criteria.js.map +1 -0
  11. package/dist/dev-shell/index.d.ts +189 -0
  12. package/dist/dev-shell/index.js +287 -0
  13. package/dist/dev-shell/index.js.map +1 -0
  14. package/dist/dev-shell/keys.d.ts +14 -0
  15. package/dist/dev-shell/keys.js +78 -0
  16. package/dist/dev-shell/keys.js.map +1 -0
  17. package/dist/dev-shell/simulator.d.ts +436 -0
  18. package/dist/dev-shell/simulator.js +1634 -0
  19. package/dist/dev-shell/simulator.js.map +1 -0
  20. package/dist/dev-shell/state.d.ts +148 -0
  21. package/dist/dev-shell/state.js +196 -0
  22. package/dist/dev-shell/state.js.map +1 -0
  23. package/dist/device-definition-resolver.d.ts +34 -0
  24. package/dist/device-definition-resolver.js +172 -0
  25. package/dist/device-definition-resolver.js.map +1 -0
  26. package/dist/device-trial.d.ts +3 -0
  27. package/dist/device-trial.js +132 -0
  28. package/dist/device-trial.js.map +1 -0
  29. package/dist/devices.d.ts +228 -0
  30. package/dist/devices.js +198 -0
  31. package/dist/devices.js.map +1 -0
  32. package/dist/dreamerAudio.d.ts +126 -0
  33. package/dist/dreamerAudio.js +135 -0
  34. package/dist/dreamerAudio.js.map +1 -0
  35. package/dist/generated/runtime-contract.d.ts +15529 -0
  36. package/dist/generated/runtime-contract.js +20470 -0
  37. package/dist/generated/runtime-contract.js.map +1 -0
  38. package/dist/index.d.ts +364 -3
  39. package/dist/index.js +1954 -13
  40. package/dist/index.js.map +1 -1
  41. package/dist/interaction-mode.d.ts +172 -0
  42. package/dist/interaction-mode.js +553 -0
  43. package/dist/interaction-mode.js.map +1 -0
  44. package/dist/internal/avatar-pose.d.ts +25 -0
  45. package/dist/internal/avatar-pose.js +46 -0
  46. package/dist/internal/avatar-pose.js.map +1 -0
  47. package/dist/internal/keyed-collection.d.ts +2 -0
  48. package/dist/internal/keyed-collection.js +12 -0
  49. package/dist/internal/keyed-collection.js.map +1 -0
  50. package/dist/internal/vehicle-detach-action.d.ts +2 -0
  51. package/dist/internal/vehicle-detach-action.js +6 -0
  52. package/dist/internal/vehicle-detach-action.js.map +1 -0
  53. package/dist/matchmaking.d.ts +433 -0
  54. package/dist/matchmaking.js +1487 -0
  55. package/dist/matchmaking.js.map +1 -0
  56. package/dist/materials.d.ts +122 -0
  57. package/dist/materials.js +217 -0
  58. package/dist/materials.js.map +1 -0
  59. package/dist/multiplayer-accessors.d.ts +100 -0
  60. package/dist/multiplayer-accessors.js +200 -0
  61. package/dist/multiplayer-accessors.js.map +1 -0
  62. package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
  63. package/dist/multiplayer-contract/avatar-pose.js +250 -0
  64. package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
  65. package/dist/multiplayer-contract/credential.d.ts +80 -0
  66. package/dist/multiplayer-contract/credential.js +5 -0
  67. package/dist/multiplayer-contract/credential.js.map +1 -0
  68. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  69. package/dist/multiplayer-contract/final-rest.js +38 -0
  70. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  71. package/dist/multiplayer-contract/index.d.ts +20 -0
  72. package/dist/multiplayer-contract/index.js +41 -0
  73. package/dist/multiplayer-contract/index.js.map +1 -0
  74. package/dist/multiplayer-contract/messages.d.ts +731 -0
  75. package/dist/multiplayer-contract/messages.js +237 -0
  76. package/dist/multiplayer-contract/messages.js.map +1 -0
  77. package/dist/multiplayer-contract/room.d.ts +177 -0
  78. package/dist/multiplayer-contract/room.js +17 -0
  79. package/dist/multiplayer-contract/room.js.map +1 -0
  80. package/dist/multiplayer-contract/state.d.ts +241 -0
  81. package/dist/multiplayer-contract/state.js +15 -0
  82. package/dist/multiplayer-contract/state.js.map +1 -0
  83. package/dist/multiplayer-final-rest.d.ts +32 -0
  84. package/dist/multiplayer-final-rest.js +217 -0
  85. package/dist/multiplayer-final-rest.js.map +1 -0
  86. package/dist/multiplayer.d.ts +624 -0
  87. package/dist/multiplayer.js +2503 -0
  88. package/dist/multiplayer.js.map +1 -0
  89. package/dist/package.json +3 -0
  90. package/dist/protocol.d.ts +859 -1
  91. package/dist/protocol.js +117 -5
  92. package/dist/protocol.js.map +1 -1
  93. package/dist/runtime-contract/index.d.ts +15 -0
  94. package/dist/runtime-contract/index.js +12 -0
  95. package/dist/runtime-contract/index.js.map +1 -0
  96. package/dist/server-clock.d.ts +25 -0
  97. package/dist/server-clock.js +88 -0
  98. package/dist/server-clock.js.map +1 -0
  99. package/dist/tsconfig.build.tsbuildinfo +1 -1
  100. package/dist/universal-vehicles.d.ts +111 -0
  101. package/dist/universal-vehicles.js +2 -0
  102. package/dist/universal-vehicles.js.map +1 -0
  103. package/dist/vault.d.ts +562 -0
  104. package/dist/vault.js +365 -0
  105. package/dist/vault.js.map +1 -0
  106. package/dist/vehicle-specialty-placement.d.ts +28 -0
  107. package/dist/vehicle-specialty-placement.js +154 -0
  108. package/dist/vehicle-specialty-placement.js.map +1 -0
  109. package/dist/vehicle-specialty-transport.d.ts +78 -0
  110. package/dist/vehicle-specialty-transport.js +183 -0
  111. package/dist/vehicle-specialty-transport.js.map +1 -0
  112. package/dist/voice.d.ts +229 -0
  113. package/dist/voice.js +1348 -0
  114. package/dist/voice.js.map +1 -0
  115. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  116. package/generated/runtime-contract/known-answer.json +20471 -0
  117. package/generated/runtime-contract/known-answer.schema.json +630 -0
  118. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  119. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  120. package/package.json +44 -5
package/dist/protocol.js CHANGED
@@ -1,13 +1,125 @@
1
1
  // postMessage protocol between a world (sandboxed iframe) and the HELIX shell
2
2
  // (the play page, or a local `helix dev` shell). This file IS the wire contract
3
- // — both sides import it; version any breaking change.
4
- export const PROTOCOL_VERSION = 1;
3
+ // — version any breaking change.
4
+ //
5
+ // SYNC OBLIGATION: the shell takes no dependency on this package, so
6
+ // helixgame.com/lib/iwp/protocol.ts hand-mirrors these shapes AND gates them at
7
+ // runtime (isWorldMessage). A type added here that isn't added there is a
8
+ // message the shell silently drops — widen both in lockstep.
9
+ //
10
+ // v2 is additive on two fronts: (1) debug — helix:init gained `debug`, and helix:log
11
+ // carries world logs to the shell when debug is on; (2) the shell-mediated platform
12
+ // API (wallet / marketplace / inventory) on a generic request/response envelope plus
13
+ // push events. The world SDK is a thin wrapper: it posts a request, the shell (which
14
+ // holds the player's session and renders the purchase popup) settles with the backend
15
+ // and posts the result.
16
+ export const PROTOCOL_VERSION = 2;
17
+ /** Additive, versioned presentation intent carried on `helix:init`. */
18
+ export const RUNTIME_FIDELITY_VERSION = 1;
19
+ export const RUNTIME_FIDELITY_VISUAL_TIERS = [
20
+ 'auto',
21
+ 'minimal',
22
+ 'low',
23
+ 'medium',
24
+ 'high',
25
+ 'ultra',
26
+ ];
27
+ export const RUNTIME_FIDELITY_RENDER_SCALES = ['1.5', '1', '0.77', '0.59'];
28
+ export const RUNTIME_PROFILE_QUALITIES = ['minimum', 'balanced', 'high', 'ultra'];
29
+ /**
30
+ * Validate untrusted handshake data and copy it into SDK-owned launch state.
31
+ * Unknown versions, unexpected fields, or invalid members fail closed to null;
32
+ * consumers then use their engine's backward-compatible Auto policy.
33
+ */
34
+ export function normalizeRuntimeFidelityIntent(value) {
35
+ if (!value || typeof value !== 'object')
36
+ return null;
37
+ const candidate = value;
38
+ if (Object.keys(candidate).length !== 4 ||
39
+ candidate.version !== RUNTIME_FIDELITY_VERSION ||
40
+ !RUNTIME_FIDELITY_VISUAL_TIERS.includes(candidate.requestedVisualTier) ||
41
+ !(candidate.renderScaleOverride === null ||
42
+ RUNTIME_FIDELITY_RENDER_SCALES.includes(candidate.renderScaleOverride)) ||
43
+ !(candidate.runtimeProfileQuality === null ||
44
+ RUNTIME_PROFILE_QUALITIES.includes(candidate.runtimeProfileQuality))) {
45
+ return null;
46
+ }
47
+ return {
48
+ version: RUNTIME_FIDELITY_VERSION,
49
+ requestedVisualTier: candidate.requestedVisualTier,
50
+ renderScaleOverride: candidate.renderScaleOverride,
51
+ runtimeProfileQuality: candidate.runtimeProfileQuality,
52
+ };
53
+ }
54
+ export const PURCHASE_STATUS_MEANING = {
55
+ Pending: { money: 'unknown', ownsAfter: false },
56
+ Granted: { money: 'charged', ownsAfter: true },
57
+ Claimed: { money: 'not-charged', ownsAfter: true },
58
+ AlreadyOwned: { money: 'not-charged', ownsAfter: true },
59
+ InsufficientFunds: { money: 'not-charged', ownsAfter: false },
60
+ MaxPerUserReached: { money: 'not-charged', ownsAfter: false },
61
+ ProductInactive: { money: 'not-charged', ownsAfter: false },
62
+ ProductNotFound: { money: 'not-charged', ownsAfter: false },
63
+ NotInWorld: { money: 'not-charged', ownsAfter: false },
64
+ Unauthorized: { money: 'not-charged', ownsAfter: false },
65
+ RateLimited: { money: 'not-charged', ownsAfter: false },
66
+ // The shell can fabricate Cancelled AFTER an attempted charge (Timeout -> Retry -> Cancel wipes the
67
+ // modal's memory that a POST happened), so not-charged cannot be certified; retaining the key turns
68
+ // that ambiguity into an idempotent replay instead of a fresh key that can double-charge.
69
+ Cancelled: { money: 'unknown', ownsAfter: false },
70
+ Failed: { money: 'not-charged', ownsAfter: false },
71
+ Timeout: { money: 'unknown', ownsAfter: false },
72
+ // Fabricated by the READ path for a row that may merely not be visible yet (the purchase POST can
73
+ // still be queued behind the per-user lock) — the popup's poll already treats it as non-terminal.
74
+ NotFound: { money: 'unknown', ownsAfter: false },
75
+ PriceChanged: { money: 'not-charged', ownsAfter: false },
76
+ };
77
+ /**
78
+ * The lens buttons, in the exact order HELIX OS renders them.
79
+ *
80
+ * These are PRESETS, not the zoom domain: effective zoom is CONTINUOUS between
81
+ * the first and last entry, and a preset is only where a tap lands. A runtime
82
+ * that clamps to these five is wrong.
83
+ */
84
+ export const CAMERA_LENS_PRESETS = [0.5, 1, 2, 3, 5];
85
+ // XR document events. The world document is shared by the SDK and the engine's XR module
86
+ // (humanoid-character); they are different bundles and never import each other, so these two
87
+ // events are the whole seam: the engine reports its immersive-session state and the SDK forwards
88
+ // it to the shell as `helix:xr-session`; the SDK mirrors Helix.prompts.set/clear back so the engine
89
+ // can draw the interaction prompt in-scene while the shell's DOM overlay cannot be seen.
90
+ // Both are STICKY, as in the engine's touchSignals.ts: the last detail is also recorded on the
91
+ // document, so a listener that attaches late starts from the current state.
92
+ // SYNC OBLIGATION: the engine's XR module declares the same names and detail shapes; the shell
93
+ // mirrors only the `helix:xr-session` WorldToShellMessage member below.
94
+ /**
95
+ * Dispatched by the ENGINE XR module on every session state change; the SDK forwards it to the shell.
96
+ * detail: { state: 'unsupported'|'idle'|'entering'|'active'|'exiting'; reason?: string; source: 'humanoid-character' }
97
+ * Sticky store: document.__helixXrSession = { state, reason }
98
+ */
99
+ export const XR_SESSION_EVENT = 'helix:xr-session';
100
+ /**
101
+ * Dispatched by the SDK when Helix.prompts.set/clear is called; the engine XR module draws it in-scene.
102
+ * detail: { prompt: { id: string; label: string; state?: 'default'|'available'|'locked'|'busy' } | null; source: 'helix-sdk' }
103
+ * Sticky store: document.__helixInteractionPrompt = detail
104
+ */
105
+ export const XR_INTERACTION_PROMPT_EVENT = 'helix:interaction-prompt';
106
+ const SHELL_MESSAGE_TYPES = new Set([
107
+ 'helix:init',
108
+ 'helix:session',
109
+ 'helix:login-result',
110
+ 'helix:response',
111
+ 'helix:event',
112
+ 'helix:voice-settings',
113
+ 'helix:voice-ptt',
114
+ 'helix:device-state',
115
+ 'helix:camera-state',
116
+ 'helix:leave',
117
+ 'helix:distribution-capability-request',
118
+ ]);
5
119
  export function isShellMessage(data) {
6
120
  return (typeof data === 'object' &&
7
121
  data !== null &&
8
122
  typeof data.type === 'string' &&
9
- (data.type === 'helix:init' ||
10
- data.type === 'helix:session' ||
11
- data.type === 'helix:login-result'));
123
+ SHELL_MESSAGE_TYPES.has(data.type));
12
124
  }
13
125
  //# sourceMappingURL=protocol.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,uDAAuD;AAEvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA6ClC,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ;QACrD,CAAE,IAAyB,CAAC,IAAI,KAAK,YAAY;YAC9C,IAAyB,CAAC,IAAI,KAAK,eAAe;YAClD,IAAyB,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAC5D,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ import { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX } from '../generated/runtime-contract.js';
2
+ export { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, };
3
+ export type HelixRuntimeContract = typeof HELIX_RUNTIME_CONTRACT;
4
+ export type RuntimeNamespace = keyof HelixRuntimeContract['namespaces'];
5
+ export type RuntimeAuthorityProfile = keyof HelixRuntimeContract['authorityProfiles'];
6
+ export type RuntimeCapability = keyof HelixRuntimeContract['capabilities'];
7
+ export type RuntimeMethodName = keyof typeof RUNTIME_METHOD_INDEX;
8
+ export type RuntimeMethodContract = (typeof RUNTIME_METHOD_INDEX)[RuntimeMethodName];
9
+ /**
10
+ * Returns the generated policy record for a public runtime SDK method.
11
+ *
12
+ * Runtime implementations use this metadata for capability discovery and
13
+ * binding generation; it does not execute or proxy the method itself.
14
+ */
15
+ export declare function getRuntimeMethod<Name extends RuntimeMethodName>(name: Name): (typeof RUNTIME_METHOD_INDEX)[Name];
@@ -0,0 +1,12 @@
1
+ import { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, } from '../generated/runtime-contract.js';
2
+ export { HELIX_RUNTIME_CONTRACT, RUNTIME_CONTRACT_DIGEST, RUNTIME_METHOD_INDEX, };
3
+ /**
4
+ * Returns the generated policy record for a public runtime SDK method.
5
+ *
6
+ * Runtime implementations use this metadata for capability discovery and
7
+ * binding generation; it does not execute or proxy the method itself.
8
+ */
9
+ export function getRuntimeMethod(name) {
10
+ return RUNTIME_METHOD_INDEX[name];
11
+ }
12
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime-contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,CAAC;AASF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAU;IAEV,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}
@@ -0,0 +1,25 @@
1
+ /** How many recent samples each source keeps. */
2
+ export declare const SERVER_CLOCK_WINDOW = 9;
3
+ /** Samples this close to the median agree with it. Wider than the `Date` header's 1 s resolution plus latency. */
4
+ export declare const SERVER_CLOCK_AGREEMENT_MS = 2000;
5
+ export type ServerClockSource = 'room' | 'http';
6
+ export declare class ServerClock {
7
+ private readonly deviceNow;
8
+ private readonly windows;
9
+ private readonly lastHeard;
10
+ private heard;
11
+ constructor(deviceNow?: () => number);
12
+ /** A server timestamp (epoch ms) received at `receivedAt` (device epoch ms; default: now). Anything unusable is ignored. */
13
+ observe(serverMs: unknown, source: ServerClockSource, receivedAt?: number): void;
14
+ /**
15
+ * An HTTP `Date` header value (null when the browser did not expose it). The header is truncated to the
16
+ * second, so the middle of that second is taken.
17
+ */
18
+ observeHttpDate(header: string | null | undefined, receivedAt?: number): void;
19
+ /** Server time minus device time, in ms, or null when no source is trusted yet. */
20
+ offsetMs(): number | null;
21
+ /** The platform's time now (epoch ms): the device clock corrected by the trusted offset, or the device clock alone. */
22
+ now(): number;
23
+ /** Whether `expiresAt` (epoch ms) has passed by the platform's clock. An unreadable expiry (NaN) never has. */
24
+ hasPassed(expiresAt: number): boolean;
25
+ }
@@ -0,0 +1,88 @@
1
+ // The platform's clock, as far as this page has seen it. Internal: not exported from the package root.
2
+ //
3
+ // A match's room ticket and a party invite carry `expiresAt` in the PLATFORM's time. Judging that against
4
+ // `Date.now()` trusts the device clock, and a device clock running fast by more than a ticket's life never
5
+ // sees a match at all (its opponents start a player short); one running slow hands the world tickets that
6
+ // are long dead. So every expiry judgement in Helix.matchmaking / Helix.party goes through `now()` here.
7
+ //
8
+ // What the SDK learns the platform's time from, without any extra request:
9
+ // - `room` every room's state is stamped with the room server's wall clock (`RoomState.serverTimeMs`, set
10
+ // each tick). Sampled on each state patch while a room is joined.
11
+ // - `http` the `Date` header of a platform API answer (matchmaking and party calls). A cross-origin page can
12
+ // read it only when the API lists it in `Access-Control-Expose-Headers`; until then the browser
13
+ // hides it and this source stays empty. One-second resolution.
14
+ //
15
+ // A sample is kept as an OFFSET (server time minus device time at receipt), so a page that slept, or a room
16
+ // that was left minutes ago, still answers correctly: the offset between two wall clocks does not drift by
17
+ // any amount that matters here. Both sources stamp the time before it travels to the device, so the estimate
18
+ // runs a little behind the platform, never ahead: it errs toward "not expired yet", and the platform has the
19
+ // last word at redeem either way.
20
+ //
21
+ // TRUST IS BOUNDED. Each source keeps its last SERVER_CLOCK_WINDOW samples. The estimate is their median, and
22
+ // it is used only while a strict majority of the window agrees with it (within SERVER_CLOCK_AGREEMENT_MS).
23
+ // So one wild answer — a cached response's stale `Date`, a proxy's own clock — cannot move it, and a single
24
+ // sample is never trusted alone. A genuine change (the device clock was corrected) is followed once most of
25
+ // the window has seen it. When both sources are trusted, the one heard from MOST RECENTLY decides: a room left
26
+ // long ago keeps its samples (they are still the best estimate when nothing newer exists), but it cannot
27
+ // overrule the platform's answers that keep arriving while the player queues. With no trusted estimate from
28
+ // either source the device clock is used, which is exactly the behaviour before this existed.
29
+ /** How many recent samples each source keeps. */
30
+ export const SERVER_CLOCK_WINDOW = 9;
31
+ /** Samples this close to the median agree with it. Wider than the `Date` header's 1 s resolution plus latency. */
32
+ export const SERVER_CLOCK_AGREEMENT_MS = 2_000;
33
+ export class ServerClock {
34
+ deviceNow;
35
+ windows = { room: [], http: [] };
36
+ // The order in which each source was last heard from (a counter, so no clock is needed to compare them).
37
+ lastHeard = { room: 0, http: 0 };
38
+ heard = 0;
39
+ constructor(deviceNow = () => Date.now()) {
40
+ this.deviceNow = deviceNow;
41
+ }
42
+ /** A server timestamp (epoch ms) received at `receivedAt` (device epoch ms; default: now). Anything unusable is ignored. */
43
+ observe(serverMs, source, receivedAt = this.deviceNow()) {
44
+ if (typeof serverMs !== 'number' || !Number.isFinite(serverMs) || serverMs <= 0 || !Number.isFinite(receivedAt))
45
+ return;
46
+ const window = this.windows[source];
47
+ window.push(serverMs - receivedAt);
48
+ if (window.length > SERVER_CLOCK_WINDOW)
49
+ window.shift();
50
+ this.lastHeard[source] = ++this.heard;
51
+ }
52
+ /**
53
+ * An HTTP `Date` header value (null when the browser did not expose it). The header is truncated to the
54
+ * second, so the middle of that second is taken.
55
+ */
56
+ observeHttpDate(header, receivedAt = this.deviceNow()) {
57
+ if (typeof header !== 'string' || header.length === 0)
58
+ return;
59
+ const parsed = Date.parse(header);
60
+ if (Number.isFinite(parsed))
61
+ this.observe(parsed + 500, 'http', receivedAt);
62
+ }
63
+ /** Server time minus device time, in ms, or null when no source is trusted yet. */
64
+ offsetMs() {
65
+ const room = trustedOffset(this.windows.room);
66
+ const http = trustedOffset(this.windows.http);
67
+ if (room === null || http === null)
68
+ return room ?? http;
69
+ return this.lastHeard.room > this.lastHeard.http ? room : http;
70
+ }
71
+ /** The platform's time now (epoch ms): the device clock corrected by the trusted offset, or the device clock alone. */
72
+ now() {
73
+ return this.deviceNow() + (this.offsetMs() ?? 0);
74
+ }
75
+ /** Whether `expiresAt` (epoch ms) has passed by the platform's clock. An unreadable expiry (NaN) never has. */
76
+ hasPassed(expiresAt) {
77
+ return Number.isFinite(expiresAt) && expiresAt <= this.now();
78
+ }
79
+ }
80
+ function trustedOffset(window) {
81
+ if (window.length < 2)
82
+ return null;
83
+ const sorted = [...window].sort((a, b) => a - b);
84
+ const median = sorted[(sorted.length - 1) >> 1];
85
+ const agreeing = sorted.filter((offset) => Math.abs(offset - median) <= SERVER_CLOCK_AGREEMENT_MS).length;
86
+ return agreeing * 2 > sorted.length ? median : null;
87
+ }
88
+ //# sourceMappingURL=server-clock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server-clock.js","sourceRoot":"","sources":["../src/server-clock.ts"],"names":[],"mappings":"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"}