@hypersoniclabs/helix-sdk 0.1.2 → 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 (115) hide show
  1. package/README.md +859 -8
  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 +65 -1
  6. package/dist/camera.js +568 -0
  7. package/dist/camera.js.map +1 -1
  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 +272 -15
  39. package/dist/index.js +1401 -91
  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 +38 -0
  66. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  67. package/dist/multiplayer-contract/final-rest.js +38 -0
  68. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  69. package/dist/multiplayer-contract/index.d.ts +11 -5
  70. package/dist/multiplayer-contract/index.js +16 -5
  71. package/dist/multiplayer-contract/index.js.map +1 -1
  72. package/dist/multiplayer-contract/messages.d.ts +461 -14
  73. package/dist/multiplayer-contract/messages.js +141 -15
  74. package/dist/multiplayer-contract/messages.js.map +1 -1
  75. package/dist/multiplayer-contract/room.d.ts +55 -4
  76. package/dist/multiplayer-contract/state.d.ts +181 -1
  77. package/dist/multiplayer-contract/state.js.map +1 -1
  78. package/dist/multiplayer-final-rest.d.ts +32 -0
  79. package/dist/multiplayer-final-rest.js +217 -0
  80. package/dist/multiplayer-final-rest.js.map +1 -0
  81. package/dist/multiplayer.d.ts +507 -16
  82. package/dist/multiplayer.js +2242 -73
  83. package/dist/multiplayer.js.map +1 -1
  84. package/dist/package.json +3 -0
  85. package/dist/protocol.d.ts +668 -5
  86. package/dist/protocol.js +101 -1
  87. package/dist/protocol.js.map +1 -1
  88. package/dist/runtime-contract/index.d.ts +15 -0
  89. package/dist/runtime-contract/index.js +12 -0
  90. package/dist/runtime-contract/index.js.map +1 -0
  91. package/dist/server-clock.d.ts +25 -0
  92. package/dist/server-clock.js +88 -0
  93. package/dist/server-clock.js.map +1 -0
  94. package/dist/tsconfig.build.tsbuildinfo +1 -1
  95. package/dist/universal-vehicles.d.ts +111 -0
  96. package/dist/universal-vehicles.js +2 -0
  97. package/dist/universal-vehicles.js.map +1 -0
  98. package/dist/vault.d.ts +562 -0
  99. package/dist/vault.js +365 -0
  100. package/dist/vault.js.map +1 -0
  101. package/dist/vehicle-specialty-placement.d.ts +28 -0
  102. package/dist/vehicle-specialty-placement.js +154 -0
  103. package/dist/vehicle-specialty-placement.js.map +1 -0
  104. package/dist/vehicle-specialty-transport.d.ts +78 -0
  105. package/dist/vehicle-specialty-transport.js +183 -0
  106. package/dist/vehicle-specialty-transport.js.map +1 -0
  107. package/dist/voice.d.ts +229 -0
  108. package/dist/voice.js +1348 -0
  109. package/dist/voice.js.map +1 -0
  110. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  111. package/generated/runtime-contract/known-answer.json +20471 -0
  112. package/generated/runtime-contract/known-answer.schema.json +630 -0
  113. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  114. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  115. package/package.json +32 -6
@@ -0,0 +1,12 @@
1
+ /** Internal adapter for Colyseus MapSchema collections and plain-record fixtures. */
2
+ export function keyedCollectionEntry(collection, id) {
3
+ if (!collection || typeof collection !== 'object')
4
+ return undefined;
5
+ const mapLike = collection;
6
+ if (typeof mapLike.get === 'function')
7
+ return mapLike.get(id);
8
+ if (!Object.prototype.hasOwnProperty.call(collection, id))
9
+ return undefined;
10
+ return collection[id];
11
+ }
12
+ //# sourceMappingURL=keyed-collection.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keyed-collection.js","sourceRoot":"","sources":["../../src/internal/keyed-collection.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAAI,UAAmB,EAAE,EAAU;IACrE,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,OAAO,GAAG,UAAsD,CAAC;IACvE,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5E,OAAQ,UAA4C,CAAC,EAAE,CAAC,CAAC;AAC3D,CAAC"}
@@ -0,0 +1,2 @@
1
+ /** Exact authored call grammar shared by trusted mount admission and sending. */
2
+ export declare function isVehicleDetachActionId(value: unknown): value is string;
@@ -0,0 +1,6 @@
1
+ const VEHICLE_DETACH_ACTION_ID = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
2
+ /** Exact authored call grammar shared by trusted mount admission and sending. */
3
+ export function isVehicleDetachActionId(value) {
4
+ return typeof value === 'string' && VEHICLE_DETACH_ACTION_ID.test(value);
5
+ }
6
+ //# sourceMappingURL=vehicle-detach-action.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vehicle-detach-action.js","sourceRoot":"","sources":["../../src/internal/vehicle-detach-action.ts"],"names":[],"mappings":"AAAA,MAAM,wBAAwB,GAAG,8BAA8B,CAAC;AAEhE,iFAAiF;AACjF,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC"}
@@ -0,0 +1,433 @@
1
+ import { ServerClock } from './server-clock.js';
2
+ /** A formed match: redeem `ticketId` with `Helix.multiplayer.switchRoom({ ticket })` before `expiresAt`. */
3
+ export type MatchFound = {
4
+ /** The ROOM ticket to redeem — not the queue ticket. */
5
+ ticketId: string;
6
+ instanceId: string;
7
+ roomType: string;
8
+ /**
9
+ * When the room ticket stops being redeemable, Unix epoch milliseconds in the PLATFORM's time (NaN if the
10
+ * backend's value is unreadable). The SDK judges it by the platform's clock as far as it knows it, not by
11
+ * the device clock alone; a device clock that is off makes `Date.now()` the wrong thing to compare it with.
12
+ */
13
+ expiresAt: number;
14
+ };
15
+ /** How full the forming match is. */
16
+ export type QueueWaiting = {
17
+ /**
18
+ * Players currently eligible to be matched: those the matcher will actually use, i.e. whose every party
19
+ * member has polled recently. May be lower than the number of players who pressed the button.
20
+ */
21
+ players: number;
22
+ /** Players the match needs. */
23
+ needed: number;
24
+ };
25
+ /**
26
+ * Why the queue ended. Absent on a `none` that never was a ticket, and after a match was redeemed.
27
+ *
28
+ * Told by the platform (it says how the caller's ticket in this world closed, for 60 s afterwards):
29
+ * - `cancelled` cancelled by the player or a party member.
30
+ * - `timeout` the queue's own waiting limit ran out.
31
+ * - `heartbeat-lapsed` nobody on the ticket polled for 15 s.
32
+ * - `member-absent` one party member did not poll for 60 s (a closed or suspended tab).
33
+ * - `party-changed` the party changed while the ticket was waiting.
34
+ * - `build-changed` the world published a new build.
35
+ * - `queue-removed` the world no longer declares the queue.
36
+ * - `replaced` the player queued in another world, which replaces this ticket.
37
+ * - `match-expired` the match's room ticket ran out, or its room closed, before this player redeemed it.
38
+ * (The SDK also concludes this one itself: see below.)
39
+ * - `ended` a reason this SDK does not know; `serverReason` has the platform's word for it.
40
+ *
41
+ * Concluded by the SDK, when the platform could not be asked (a platform reason is preferred when there is one):
42
+ * - `heartbeat-lost` no poll got through for 15 s, so the platform has cancelled the waiting ticket.
43
+ * - `match-expired` the match's room ticket ran out (by the platform's clock) without being redeemed.
44
+ * - `refused` the platform refused the poll for good (feature off, no permission, guest session).
45
+ * - `session-changed` the session ended or another player signed in.
46
+ * - `left` the world was left (the shell's leave message).
47
+ */
48
+ export type QueueEndReason = 'cancelled' | 'timeout' | 'heartbeat-lapsed' | 'member-absent' | 'party-changed' | 'build-changed' | 'queue-removed' | 'replaced' | 'ended' | 'heartbeat-lost' | 'match-expired' | 'refused' | 'session-changed' | 'left';
49
+ /**
50
+ * Where this player stands in matchmaking. `none` = not queued (never queued, cancelled, expired, or the
51
+ * match's room ticket was redeemed or ran out), with `reason` when the SDK concluded it. `waiting` carries
52
+ * `queueId` and, once the backend has reported it, `waiting`. `matched` carries `match`.
53
+ */
54
+ export type QueueStatus = {
55
+ status: 'none' | 'waiting' | 'matched';
56
+ queueId?: string;
57
+ waiting?: QueueWaiting;
58
+ match?: MatchFound;
59
+ reason?: QueueEndReason;
60
+ /** The platform's own reason, verbatim, whenever it gave one (also when `reason` recognised it). */
61
+ serverReason?: string;
62
+ };
63
+ export type PartyMember = {
64
+ userId: string;
65
+ displayName: string;
66
+ };
67
+ /** A code other players can type to join a party. */
68
+ export type PartyCode = {
69
+ code: string;
70
+ /** Unix epoch milliseconds (NaN if the backend's value is unreadable). */
71
+ expiresAt: number;
72
+ };
73
+ export type Party = {
74
+ id: string;
75
+ leaderId: string;
76
+ maxSize: number;
77
+ members: PartyMember[];
78
+ /** The party's current join code. Present only for the leader, and only while a code exists. */
79
+ code?: PartyCode;
80
+ };
81
+ /** An invite this player has received and not yet answered. */
82
+ export type PartyInvite = {
83
+ id: string;
84
+ partyId: string;
85
+ from: PartyMember;
86
+ /** Unix epoch milliseconds (NaN if the backend's value is unreadable). */
87
+ expiresAt: number;
88
+ };
89
+ /** The player's party (null when in none) and their pending incoming invites. */
90
+ export type PartyState = {
91
+ party: Party | null;
92
+ invites: PartyInvite[];
93
+ };
94
+ /** What `Helix.party.invite` returns: the invite just sent. */
95
+ export type PartyInviteReceipt = {
96
+ inviteId: string;
97
+ /** Unix epoch milliseconds (NaN if the backend's value is unreadable). */
98
+ expiresAt: number;
99
+ };
100
+ /**
101
+ * Why a matchmaking call failed. The backend's refusal `code` is what is matched, not the HTTP status alone.
102
+ * - `unknown-queue` the world's manifest declares no such queue.
103
+ * - `already-queued` this player (or their party) already holds a waiting ticket in THIS world. The call
104
+ * rejects, the SDK makes sure that ticket is being polled, and `onStatus` reports it.
105
+ * (A waiting ticket in another world is not an error: enqueueing here replaces it.)
106
+ * - `already-matched` a match already stands: `cancel()` came too late, or `enqueue()` was called while a
107
+ * match is unredeemed. `error.match` is the match and `onMatch` fires for it. From
108
+ * `enqueue()` it may be null: then the pending match belongs to another member of
109
+ * your party (the platform does not hand one member's room ticket to another;
110
+ * `error.memberUserId` names them), and your own status stays what it was.
111
+ * - `not-party-leader` in a party, only the leader queues.
112
+ * - `party-too-large` the party does not fit one team of this queue.
113
+ * - `party-changed` the party kept changing while the request ran. Nothing happened; safe to call
114
+ * again. The SDK has already retried it twice.
115
+ * - `guests-cannot-queue` the session is a guest; checked locally first, with no request.
116
+ * - `rate-limited` backend `queue-rate-limit`, or any 429.
117
+ * - `missing-permission` the world's manifest lacks the `multiplayer` permission (the platform's
118
+ * "Insufficient world scopes" 401). Final: asking again cannot help.
119
+ * - `unavailable` matchmaking is not enabled on this platform (`matchmaking-disabled`).
120
+ * - `not-ready` no world session, no world id, no API base, or the world was left — nothing was sent.
121
+ * - `invalid-argument` a bad argument — nothing was sent.
122
+ * - `request-failed` anything else: no answer within the timeout (`status` null), a 5xx, any other
123
+ * 401 (an expired or missing token), a 404 with no refusal code, or a refusal code
124
+ * this SDK does not know (`backendCode` has it).
125
+ */
126
+ export type HelixMatchmakingErrorCode = 'unknown-queue' | 'already-queued' | 'already-matched' | 'not-party-leader' | 'party-too-large' | 'party-changed' | 'guests-cannot-queue' | 'rate-limited' | 'missing-permission' | 'unavailable' | 'not-ready' | 'invalid-argument' | 'request-failed';
127
+ /** The typed failure of every `Helix.matchmaking` promise. Branch on `code`; `status` is the HTTP status when there was one. */
128
+ export declare class HelixMatchmakingError extends Error {
129
+ readonly code: HelixMatchmakingErrorCode;
130
+ readonly status: number | null;
131
+ /** The backend's own refusal code, verbatim, when the response carried one. */
132
+ readonly backendCode: string | null;
133
+ /** With `already-matched`: the match the ticket was already in. */
134
+ readonly match: MatchFound | null;
135
+ /** With `already-matched` from `enqueue()` and no `match`: the party member who holds the pending match. */
136
+ readonly memberUserId: string | null;
137
+ constructor(code: HelixMatchmakingErrorCode, message: string, status?: number | null, backendCode?: string | null, cause?: unknown, match?: MatchFound | null, memberUserId?: string | null);
138
+ }
139
+ /**
140
+ * Why a party call failed.
141
+ * - `not-party-leader` only the leader invites, kicks and promotes.
142
+ * - `cannot-invite` the target is not a friend, and is not invitable as a stranger either: that needs
143
+ * them to be in this world AND to have public presence with activity sharing on
144
+ * (the account default is friends-only). A block also gives this. Use a join code.
145
+ * - `party-full` no room left (inviting or accepting).
146
+ * - `too-many-invites` the party already has its limit of pending invites.
147
+ * - `already-in-party` you are in a party of two or more: leave it before accepting an invite or joining
148
+ * by code. From a party of one (your own invite or code created it) you are moved.
149
+ * - `code-not-found` no party has that join code (mistyped, expired or revoked).
150
+ * - `party-changed` the party kept changing while the request ran. Nothing happened; safe to call
151
+ * again. The SDK has already retried it twice.
152
+ * - `not-in-party` you are in no party (leave, kick, promote).
153
+ * - `unknown-party-member` that player is not in your party (kick, promote).
154
+ * - `invite-not-found` the invite does not exist (or is not yours).
155
+ * - `invite-expired` the invite ran out.
156
+ * - `guests-cannot-party` the session is a guest; checked locally first, with no request.
157
+ * - `rate-limited` backend `invite-rate-limit`, or any 429.
158
+ * - `missing-permission` the world's manifest lacks the `multiplayer` permission (the platform's
159
+ * "Insufficient world scopes" 401). Final: asking again cannot help.
160
+ * - `unavailable` parties are not enabled on this platform (`parties-disabled`).
161
+ * - `not-ready` / `invalid-argument` / `request-failed` as for HelixMatchmakingError.
162
+ */
163
+ export type HelixPartyErrorCode = 'not-party-leader' | 'cannot-invite' | 'party-full' | 'too-many-invites' | 'already-in-party' | 'party-changed' | 'not-in-party' | 'unknown-party-member' | 'invite-not-found' | 'invite-expired' | 'code-not-found' | 'guests-cannot-party' | 'rate-limited' | 'missing-permission' | 'unavailable' | 'not-ready' | 'invalid-argument' | 'request-failed';
164
+ /** The typed failure of every `Helix.party` promise. Branch on `code`; `status` is the HTTP status when there was one. */
165
+ export declare class HelixPartyError extends Error {
166
+ readonly code: HelixPartyErrorCode;
167
+ readonly status: number | null;
168
+ /** The backend's own refusal code, verbatim, when the response carried one. */
169
+ readonly backendCode: string | null;
170
+ constructor(code: HelixPartyErrorCode, message: string, status?: number | null, backendCode?: string | null, cause?: unknown);
171
+ }
172
+ /** What matchmaking needs from the party namespace: to be told how many members the player's party has. */
173
+ export interface PartyWatch {
174
+ /**
175
+ * Keeps the party poll alive while watched. `cb` gets the member count (0 = no party) on every fresh
176
+ * answer. While the tab is hidden the poll rests unless there is a reason to keep it: a party of two or
177
+ * more, a world subscribed to party events, or `busy()` (the watcher has work that depends on it).
178
+ * `update()` tells the party that `busy()` may have changed.
179
+ */
180
+ watch(cb: (members: number) => void, busy?: () => boolean): {
181
+ stop(): void;
182
+ update(): void;
183
+ };
184
+ }
185
+ export interface PlatformSocialHost {
186
+ isInitialized(): boolean;
187
+ getToken(): string | null;
188
+ getWorldId(): string | null;
189
+ getUserId(): string | null;
190
+ resolveApiBase(token: string | null): string | null;
191
+ /**
192
+ * The platform's clock as this page has learned it (see server-clock.ts): every expiry judgement uses it, and
193
+ * every platform answer feeds it. The SDK singleton shares one with Helix.multiplayer, which feeds it the room
194
+ * clock. Optional: without one, the namespaces built on the same host share a clock of their own.
195
+ */
196
+ readonly clock?: ServerClock;
197
+ }
198
+ /** While a queue ticket is waiting or matched. Also the server heartbeat (a waiting ticket unpolled for 15 s is cancelled). */
199
+ export declare const MATCHMAKING_POLL_MS = 3000;
200
+ /**
201
+ * While this player is in a party of two or more, is not queued, and the world listens to matchmaking: how
202
+ * often the SDK looks for a ticket the party's leader may have queued.
203
+ */
204
+ export declare const MATCHMAKING_IDLE_POLL_MS = 5000;
205
+ /** While a world is subscribed to party changes or invites, or listens to matchmaking. */
206
+ export declare const PARTY_POLL_MS = 5000;
207
+ /** A platform request with no answer after this long is abandoned (and aborted), so it cannot stall a poll loop. */
208
+ export declare const PLATFORM_REQUEST_TIMEOUT_MS = 8000;
209
+ /**
210
+ * The bound for the queue STATUS POLL alone. Shorter than the general one because the poll is a heartbeat
211
+ * against a 15 s server limit: at 8 s one hung poll would leave an 11-12 s gap; at 5 s the next tick after it
212
+ * still lands with room to spare.
213
+ */
214
+ export declare const MATCHMAKING_POLL_TIMEOUT_MS = 5000;
215
+ /** The server's patience: a waiting ticket not polled for this long has been cancelled. */
216
+ export declare const MATCHMAKING_HEARTBEAT_LOST_MS = 15000;
217
+ /** The longest a failing poll loop waits between attempts. */
218
+ export declare const POLL_BACKOFF_MAX_MS = 30000;
219
+ /** How often a request refused with `party-changed` (safe to retry) is sent again before the refusal is surfaced. */
220
+ export declare const PARTY_CHANGED_RETRIES = 2;
221
+ /** The pause before the first such retry; the second waits twice as long. */
222
+ export declare const PARTY_CHANGED_RETRY_MS = 250;
223
+ export declare class HelixMatchmaking {
224
+ private readonly host;
225
+ private readonly party;
226
+ private readonly lane;
227
+ private readonly poller;
228
+ private readonly idle;
229
+ private partyMembers;
230
+ private partyWatch;
231
+ private reportedEnding;
232
+ private endedLocally;
233
+ private refused;
234
+ private readonly backoff;
235
+ private readonly statusListeners;
236
+ private readonly matchListeners;
237
+ private last;
238
+ private generation;
239
+ private flight;
240
+ private lastAnswerAt;
241
+ private lastRanAt;
242
+ private wokeAt;
243
+ private wake;
244
+ private requests;
245
+ private resumed;
246
+ private left;
247
+ private mutations;
248
+ private readonly seenMatches;
249
+ private undelivered;
250
+ private readonly clock;
251
+ constructor(host: PlatformSocialHost, party?: PartyWatch | null);
252
+ /**
253
+ * Join one of the world's declared queues (manifest `matchmaking.queues`). In a party, only the leader
254
+ * queues, and the whole party is queued together. Resolves `{ status: 'waiting', queueId, waiting? }` and
255
+ * starts the 3 s poll that keeps the ticket alive and drives `onStatus` / `onMatch`. Calls to `enqueue`
256
+ * and `cancel` are carried out one at a time, in the order they were made. While a match still stands
257
+ * unredeemed it rejects with `already-matched` (`error.match`), the status is `matched` and `onMatch`
258
+ * fires if that match was not delivered yet.
259
+ */
260
+ enqueue(queueId: string): Promise<QueueStatus>;
261
+ /**
262
+ * Leave the queue. Idempotent: resolves whether a waiting ticket was cancelled or there was none. A party
263
+ * member cancelling cancels the whole party's ticket. If the ticket has ALREADY MATCHED it rejects with
264
+ * `already-matched` (`error.match` is the match), the status is `matched`, and `onMatch` fires — a match
265
+ * is never reported as `none`. If the request got no usable answer, the SDK asks the platform what
266
+ * happened before rejecting, so a match that formed meanwhile is still delivered.
267
+ */
268
+ cancel(): Promise<void>;
269
+ /**
270
+ * Ask the platform where this player stands now. What it finds is treated exactly like a poll's answer:
271
+ * `onStatus` / `onMatch` fire if it is news, and polling starts or stops to match.
272
+ */
273
+ status(): Promise<QueueStatus>;
274
+ /**
275
+ * Called whenever the queue status CHANGES (waiting counts, matched, back to none) — not once per poll.
276
+ * A `none` the SDK concluded by itself carries a `reason` (see QueueEndReason). Subscribing also checks,
277
+ * once per session, whether a ticket from before a reload is still alive.
278
+ */
279
+ onStatus(cb: (status: QueueStatus) => void): () => void;
280
+ /**
281
+ * Called exactly once per match (per room `ticketId`), however it was discovered: a poll, an explicit
282
+ * `status()`, a `cancel()` that came too late, or the first check after a reload. A match found while
283
+ * nobody was listening is handed to the first subscriber, unless it has expired or the status has since
284
+ * gone back to `none`. Redeem it with `Helix.multiplayer.switchRoom({ ticket: match.ticketId })`.
285
+ * Expiry is judged by the platform's clock (learned from a joined room's state and, where the browser
286
+ * exposes it, the `Date` header of platform answers), and by the device clock only when nothing is known.
287
+ */
288
+ onMatch(cb: (match: MatchFound) => void): () => void;
289
+ /** @internal Helix.init() resolved: a world that subscribed before then is served now. */
290
+ ready(): void;
291
+ /**
292
+ * @internal helix:leave. Subscribers are told the queue is over (`reason: 'left'` — the ticket lapses with
293
+ * the heartbeat), every timer and listener stops, and nothing is sent again until a new session.
294
+ */
295
+ teardown(): void;
296
+ /**
297
+ * @internal The session ended or changed hands: nothing known about the old one applies. Subscribers are
298
+ * told (`reason: 'session-changed'`), and if there is a new session and someone is subscribed, its ticket
299
+ * is looked up.
300
+ */
301
+ reset(): void;
302
+ private get listeners();
303
+ private subscribed;
304
+ private unsubscribed;
305
+ private syncIdle;
306
+ private request;
307
+ private exclusive;
308
+ private queuesPath;
309
+ private commit;
310
+ private refresh;
311
+ private resume;
312
+ private woke;
313
+ private lapsed;
314
+ private wokeIntoSilence;
315
+ private poll;
316
+ private apply;
317
+ private end;
318
+ }
319
+ export declare class HelixParty implements PartyWatch {
320
+ private readonly host;
321
+ private readonly lane;
322
+ private readonly watchers;
323
+ private members;
324
+ private followingVisibility;
325
+ private readonly poller;
326
+ private readonly backoff;
327
+ private readonly changeListeners;
328
+ private readonly inviteListeners;
329
+ private readonly errorListeners;
330
+ private baseline;
331
+ private readonly seenInvites;
332
+ private generation;
333
+ private pollingGeneration;
334
+ private refusal;
335
+ private left;
336
+ private readonly clock;
337
+ constructor(host: PlatformSocialHost);
338
+ /** The player's party (null when in none) and their pending incoming invites, fresh from the platform. */
339
+ get(): Promise<PartyState>;
340
+ /**
341
+ * Called when the party state actually changed (a member joined or left, the leader changed, an invite
342
+ * arrived or went away). The first answer after subscribing is the baseline, not a change — read it with
343
+ * `get()`. The platform is polled every 5 s only while there is at least one `onChange` / `onInvite`
344
+ * subscriber; when the last one unsubscribes the baseline is forgotten.
345
+ */
346
+ onChange(cb: (state: PartyState) => void): () => void;
347
+ /**
348
+ * Called once per incoming invite id, including invites already pending when the world subscribed.
349
+ * Invites are only ever announced from a fresh answer (subscribing asks for one), and never once expired
350
+ * (by the platform's clock, as for a match).
351
+ */
352
+ onInvite(cb: (invite: PartyInvite) => void): () => void;
353
+ /**
354
+ * Called when the background poll behind `onChange` / `onInvite` meets a FINAL refusal and stops: the
355
+ * world lacks the `multiplayer` permission (`missing-permission`), parties are not enabled (`unavailable`),
356
+ * or the session is a guest (`guests-cannot-party`). Fires once per refusal; a subscriber added afterwards
357
+ * is told too. The poll starts again by itself with a new or refreshed session, and as soon as any party
358
+ * call of the world's own (`get()`, `invite()`, …) is answered successfully. Every other failure — no
359
+ * answer, a 5xx, a 429, a 401 from an expired token, any other refusal — is retried with backoff (up to
360
+ * POLL_BACKOFF_MAX_MS apart) and is not reported here; failures of calls the world makes itself reject
361
+ * those calls.
362
+ */
363
+ onError(cb: (error: HelixPartyError) => void): () => void;
364
+ /**
365
+ * Invite an accepted friend, or any account with a live session in this same world. Creates the party
366
+ * when the caller has none (they become its leader). The recipient must accept.
367
+ */
368
+ invite(userId: string): Promise<PartyInviteReceipt>;
369
+ /**
370
+ * Accept an incoming invite and join that party. Resolves the party joined. From a party of one the
371
+ * caller is moved into the new party; from a larger one it is `already-in-party`.
372
+ */
373
+ accept(inviteId: string): Promise<Party>;
374
+ /**
375
+ * Leader only: make a join code for the party — the way players who are not friends group up (an invite
376
+ * to a non-friend only reaches a player whose presence is public). Creates a party of one when the caller
377
+ * has none. The code also appears as `party.code` in the leader's `get()` / `onChange` state.
378
+ */
379
+ createCode(): Promise<PartyCode>;
380
+ /** Leader only: withdraw the party's join code. Resolves whether or not there was one. */
381
+ revokeCode(): Promise<void>;
382
+ /**
383
+ * Join a party by its code. What the player typed is trimmed and upper-cased first; an empty code, one
384
+ * containing whitespace or one longer than 64 characters is rejected locally (`invalid-argument`).
385
+ * Resolves the party joined. From a party of one the caller is moved; from a larger one it is
386
+ * `already-in-party`.
387
+ */
388
+ join(code: string): Promise<Party>;
389
+ /** Decline an incoming invite (or, as the leader, revoke one that was sent). */
390
+ decline(inviteId: string): Promise<void>;
391
+ /** Leave the party. The leader leaving promotes the longest-standing member; the last member leaving ends it. */
392
+ leave(): Promise<void>;
393
+ /** Leader only: remove a member. */
394
+ kick(userId: string): Promise<void>;
395
+ /** Leader only: hand leadership to another member. Resolves the party. */
396
+ promote(userId: string): Promise<Party>;
397
+ /** @internal See PartyWatch. Told the last known size at once when the poll is already running. */
398
+ watch(cb: (members: number) => void, busy?: () => boolean): {
399
+ stop(): void;
400
+ update(): void;
401
+ };
402
+ /** @internal Helix.init() resolved: a world that subscribed before then is served now. */
403
+ ready(): void;
404
+ /**
405
+ * @internal helix:leave. Every timer and listener stops and nothing is sent again until a new session.
406
+ * No change is reported: a party is platform-level and outlives the world.
407
+ */
408
+ teardown(): void;
409
+ /**
410
+ * @internal The session ended or changed hands. The old player's party is not this session's: subscribers
411
+ * who knew of one are told there is none, and if there is a new session its party is polled and compared
412
+ * against that.
413
+ */
414
+ reset(): void;
415
+ /** @internal The same player's session was refreshed (a new token): a poll that was refused gets another chance. */
416
+ sessionRefreshed(): void;
417
+ private recovered;
418
+ private get listeners();
419
+ private get subscribers();
420
+ private tellWatchers;
421
+ private followVisibility;
422
+ private visibilityChanged;
423
+ private restingWhileHidden;
424
+ private unsubscribed;
425
+ private id;
426
+ private partyFrom;
427
+ private act;
428
+ private refresh;
429
+ private sync;
430
+ private poll;
431
+ private pollFailed;
432
+ private apply;
433
+ }