@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1

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 (75) hide show
  1. package/MIGRATION.md +64 -0
  2. package/README.md +19 -0
  3. package/dist/client.d.ts +98 -5
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +74 -5
  6. package/dist/crowdy-client.d.ts +31 -0
  7. package/dist/crowdy-client.d.ts.map +1 -1
  8. package/dist/crowdy-client.js +8 -0
  9. package/dist/domains/actors.d.ts +88 -5
  10. package/dist/domains/actors.d.ts.map +1 -1
  11. package/dist/domains/actors.js +89 -6
  12. package/dist/domains/apps.d.ts +95 -41
  13. package/dist/domains/apps.d.ts.map +1 -1
  14. package/dist/domains/apps.js +80 -33
  15. package/dist/domains/auth.d.ts +139 -19
  16. package/dist/domains/auth.d.ts.map +1 -1
  17. package/dist/domains/auth.js +137 -17
  18. package/dist/domains/channels.d.ts +264 -5
  19. package/dist/domains/channels.d.ts.map +1 -1
  20. package/dist/domains/channels.js +264 -5
  21. package/dist/domains/chunks.d.ts +116 -3
  22. package/dist/domains/chunks.d.ts.map +1 -1
  23. package/dist/domains/chunks.js +116 -3
  24. package/dist/domains/gameModel.d.ts +412 -6
  25. package/dist/domains/gameModel.d.ts.map +1 -1
  26. package/dist/domains/gameModel.js +412 -6
  27. package/dist/domains/platform.d.ts +36 -20
  28. package/dist/domains/platform.d.ts.map +1 -1
  29. package/dist/domains/platform.js +29 -18
  30. package/dist/domains/serverStatus.d.ts +74 -6
  31. package/dist/domains/serverStatus.d.ts.map +1 -1
  32. package/dist/domains/serverStatus.js +74 -6
  33. package/dist/domains/state.d.ts +50 -2
  34. package/dist/domains/state.d.ts.map +1 -1
  35. package/dist/domains/state.js +50 -2
  36. package/dist/domains/teams.d.ts +265 -7
  37. package/dist/domains/teams.d.ts.map +1 -1
  38. package/dist/domains/teams.js +267 -9
  39. package/dist/domains/teleport.d.ts +30 -2
  40. package/dist/domains/teleport.d.ts.map +1 -1
  41. package/dist/domains/teleport.js +30 -2
  42. package/dist/domains/udp.d.ts +341 -5
  43. package/dist/domains/udp.d.ts.map +1 -1
  44. package/dist/domains/udp.js +341 -5
  45. package/dist/domains/users.d.ts +42 -11
  46. package/dist/domains/users.d.ts.map +1 -1
  47. package/dist/domains/users.js +41 -10
  48. package/dist/domains/voxels.d.ts +107 -2
  49. package/dist/domains/voxels.d.ts.map +1 -1
  50. package/dist/domains/voxels.js +107 -2
  51. package/dist/errors.d.ts +116 -0
  52. package/dist/errors.d.ts.map +1 -1
  53. package/dist/errors.js +100 -0
  54. package/dist/generated/graphql.d.ts +1787 -110
  55. package/dist/generated/graphql.d.ts.map +1 -1
  56. package/dist/generated/graphql.js +75 -9
  57. package/dist/index.d.ts +2 -1
  58. package/dist/index.d.ts.map +1 -1
  59. package/dist/index.js +2 -1
  60. package/dist/realtime.d.ts +226 -0
  61. package/dist/realtime.d.ts.map +1 -1
  62. package/dist/realtime.js +90 -0
  63. package/dist/session.d.ts +46 -0
  64. package/dist/session.d.ts.map +1 -1
  65. package/dist/session.js +35 -0
  66. package/dist/types.d.ts +429 -0
  67. package/dist/types.d.ts.map +1 -1
  68. package/dist/types.js +53 -0
  69. package/dist/utils.d.ts +86 -0
  70. package/dist/utils.d.ts.map +1 -1
  71. package/dist/utils.js +86 -0
  72. package/dist/world.d.ts +192 -0
  73. package/dist/world.d.ts.map +1 -1
  74. package/dist/world.js +170 -0
  75. package/package.json +1 -1
@@ -3,37 +3,318 @@ import type { SubscriptionManager, UdpNotificationHandlers } from '../subscripti
3
3
  import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables } from '../generated/graphql.js';
4
4
  import type { SpatialNotification } from '../realtime.js';
5
5
  /**
6
- * UDP proxy access for browser-style clients that can't open raw UDP
7
- * sockets. Exposed as `client.udp`. All send mutations go over the same
8
- * GraphQL HTTP endpoint and are forwarded to the assigned game server by
9
- * the API's UDP proxy module. Notifications come back over a single shared
10
- * WebSocket subscription managed by `SubscriptionManager`.
6
+ * UDP proxy access for browser-style clients that can't open raw UDP sockets.
7
+ * Exposed as `client.udp`; for game loops prefer the ergonomic, app-scoped
8
+ * facade `client.world(appId)`, which passes `appId` for you and tracks the
9
+ * current chunk so you don't repeat it on every send.
10
+ *
11
+ * All send mutations go over the **game-api** GraphQL HTTP endpoint and are
12
+ * forwarded to the assigned game server by the API's UDP proxy module;
13
+ * notifications come back over a single shared `graphql-transport-ws`
14
+ * WebSocket (same game-api endpoint) managed by `SubscriptionManager` — the
15
+ * first subscriber opens it and the last to unsubscribe closes it. Every call
16
+ * requires an authenticated session carrying a **bearer game token** (minted
17
+ * by the management-api, set via `client.auth.login()` or `client.setToken()`);
18
+ * a UDP proxy session is opened lazily on the first send or subscribe if you
19
+ * didn't call {@link connect} first.
20
+ *
21
+ * Each packet type comes in two shapes:
22
+ * - Plain `send*` — fire-and-forget. Resolves to a `boolean` ack that the proxy
23
+ * *accepted the datagram for sending*; it does **not** confirm the world
24
+ * applied it or that it was delivered.
25
+ * - `send*AndWait` — allocates a `sequenceNumber`, then resolves with the
26
+ * server's matching echo (a {@link SpatialNotification}) correlated by that
27
+ * sequence, or rejects on timeout. Only actor and voxel updates are echoed
28
+ * back to the sender (`ActorUpdateResponse` / `VoxelUpdateResponse`); audio,
29
+ * text, and event sends are not.
30
+ *
31
+ * Spatial caveats: a `sequenceNumber` is a uint8 (0-255) used for
32
+ * **correlation only** — not an idempotency key, and the server does not dedupe
33
+ * replays. The **first** spatial message to a brand-new chunk may be dropped
34
+ * server-side while grid permissions load, so clients should re-send (the
35
+ * two-client tests register twice for this reason). To receive any
36
+ * `...AndWait` echo or notification you must have an active {@link subscribe}.
11
37
  */
12
38
  export declare class UdpAPI {
13
39
  private gql;
14
40
  private subs;
15
41
  private readonly sequences;
16
42
  constructor(gql: GraphQLClient, subs: SubscriptionManager);
43
+ /**
44
+ * Open (or re-fetch) the UDP proxy session for this game token. Idempotent:
45
+ * if a session is already open it returns the existing status; on first open
46
+ * it binds a socket and selects the game server with the fewest clients.
47
+ * Calling this is optional — any `send*` mutation or {@link subscribe} opens a
48
+ * session lazily — but use it to pre-warm the socket or surface auth/
49
+ * connectivity problems eagerly. To force a fresh socket, call
50
+ * {@link disconnect} first.
51
+ *
52
+ * @returns The {@link UdpProxyConnectionStatus}: `connected`, plus (when
53
+ * connected) `serverIp6`, `serverClientPort`, and `lastMessageTime`.
54
+ * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the request carries no
55
+ * valid bearer game token.
56
+ */
17
57
  connect(): Promise<ConnectUdpProxyMutation['connectUdpProxy']>;
58
+ /**
59
+ * Close the UDP proxy session and socket for this game token. Note that
60
+ * unsubscribing from notifications does **not** disconnect — call this (or
61
+ * rely on the server's inactivity timeout) to release the session, e.g. to
62
+ * force a fresh socket on the next {@link connect} or send.
63
+ *
64
+ * @returns `true` once the session has been closed.
65
+ * @throws {CrowdyGraphQLError} on auth failures.
66
+ */
18
67
  disconnect(): Promise<boolean>;
68
+ /**
69
+ * Read the current UDP proxy session status **without** opening one. With no
70
+ * game token it simply reports `connected: false` rather than throwing.
71
+ * Inspect `lastMessageTime` to gauge connection health.
72
+ *
73
+ * @returns The {@link UdpProxyConnectionStatus} (`connected`, plus when
74
+ * connected `serverIp6`, `serverClientPort`, and `lastMessageTime`).
75
+ */
19
76
  connectionStatus(): Promise<UdpProxyConnectionStatusQuery['udpProxyConnectionStatus']>;
77
+ /**
78
+ * Send an actor (player/NPC) state update for spatial replication to nearby
79
+ * chunks. Fire-and-forget; opens a UDP proxy session automatically if none
80
+ * exists. The applied echo (`ActorUpdateResponse`) and any failure
81
+ * (`GenericErrorResponse`) arrive asynchronously on {@link subscribe},
82
+ * correlated by `sequenceNumber`; use {@link sendActorUpdateAndWait} to await
83
+ * that echo inline.
84
+ *
85
+ * @param input - {@link ActorUpdateRequestInput}:
86
+ * - `appId` — owning app id (`BigInt` as a decimal string).
87
+ * - `chunk` — `{ x, y, z }` chunk address; each axis is a signed int64
88
+ * decimal string. A chunk is a 16x16x16 voxel cube.
89
+ * - `uuid` — the actor id: exactly 32 ASCII characters (the UDP-wire id),
90
+ * **not** an RFC-4122 UUID.
91
+ * - `state` — actor state blob, base64-encoded; may be `''` for a
92
+ * registration-only update.
93
+ * - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
94
+ * to 8 for actor updates.
95
+ * - `decayRate` — replication decay algorithm: 0 none, 1 exponential,
96
+ * 2 linear 50%, 3 linear 25%, 4 linear 10%, 5 linear 5%; defaults to 1
97
+ * (exponential) for actor updates.
98
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id; not an
99
+ * idempotency key.
100
+ * @returns `true` when the datagram was accepted for sending to the game
101
+ * server — **not** confirmation that the world applied it.
102
+ * @throws {CrowdyGraphQLError} e.g. `UNAUTHENTICATED` without a valid game
103
+ * token, or `BAD_USER_INPUT` for a malformed packet.
104
+ */
20
105
  sendActorUpdate(input: SendActorUpdateMutationVariables['input']): Promise<boolean>;
106
+ /**
107
+ * Send an actor update and wait for the server's applied echo. Allocates a
108
+ * `sequenceNumber` when `input.sequenceNumber` is omitted, registers the wait
109
+ * *before* sending, then resolves with the matching `ActorUpdateResponse`.
110
+ * Requires an active {@link subscribe} so the echo can be delivered over the
111
+ * shared WebSocket.
112
+ *
113
+ * @param input - {@link ActorUpdateRequestInput} (see {@link sendActorUpdate}
114
+ * for field units/encoding). Omit `sequenceNumber` to let the SDK allocate
115
+ * one.
116
+ * @param options - `timeoutMs`: how long to wait for the echo, in
117
+ * milliseconds; defaults to the client's realtime `waitTimeoutMs` (5000).
118
+ * @returns The correlated {@link SpatialNotification} (the `ActorUpdateResponse`
119
+ * echo).
120
+ * @throws {CrowdyGraphQLError} if the underlying send is rejected.
121
+ * @throws {CrowdyTimeoutError} if the HTTP send leg exceeds the client's
122
+ * request timeout.
123
+ * @throws {CrowdyRealtimeError} if no echo arrives within `timeoutMs`
124
+ * (`code === 'UDP_SEQUENCE_TIMEOUT'`, retryable), or the server returns a
125
+ * matching `GenericErrorResponse` (its `code` is the server's `errorCode`).
126
+ * @example
127
+ * ```ts
128
+ * const unsubscribe = client.udp.subscribe({}, appId); // echoes need an open WS
129
+ * const echo = await client.udp.sendActorUpdateAndWait({
130
+ * appId,
131
+ * chunk: { x: '0', y: '0', z: '0' },
132
+ * uuid,
133
+ * state: 'AA==',
134
+ * distance: 8,
135
+ * });
136
+ * console.log(echo.__typename, echo.sequenceNumber);
137
+ * ```
138
+ */
21
139
  sendActorUpdateAndWait(input: SendActorUpdateMutationVariables['input'], options?: {
22
140
  timeoutMs?: number;
23
141
  }): Promise<SpatialNotification>;
142
+ /**
143
+ * Send a single voxel (block) update for spatial replication to nearby
144
+ * chunks. Fire-and-forget; opens a UDP proxy session automatically. The
145
+ * applied echo (`VoxelUpdateResponse`) and failures (`GenericErrorResponse`)
146
+ * arrive asynchronously on {@link subscribe}; use
147
+ * {@link sendVoxelUpdateAndWait} to await the echo inline.
148
+ *
149
+ * @param input - {@link VoxelUpdateRequestInput}:
150
+ * - `appId` — owning app id (`BigInt` as a decimal string).
151
+ * - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings); a
152
+ * chunk is a 16x16x16 voxel cube.
153
+ * - `uuid` — 32-ASCII-character actor/source id (not RFC-4122).
154
+ * - `voxel` — `{ x, y, z }` voxel coordinates within the chunk; each is an
155
+ * int16 (-32768 to 32767).
156
+ * - `voxelType` — the new voxel type id.
157
+ * - `voxelState` — voxel state blob, base64-encoded.
158
+ * - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
159
+ * to 8 for voxel updates.
160
+ * - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
161
+ * defaults to 0 (none) for voxel updates.
162
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id.
163
+ * @returns `true` when accepted for sending — **not** confirmation the world
164
+ * applied the change.
165
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
166
+ */
24
167
  sendVoxelUpdate(input: SendVoxelUpdateMutationVariables['input']): Promise<boolean>;
168
+ /**
169
+ * Send a voxel update and wait for the server's applied `VoxelUpdateResponse`
170
+ * echo. Allocates a `sequenceNumber` when omitted and requires an active
171
+ * {@link subscribe}.
172
+ *
173
+ * @param input - {@link VoxelUpdateRequestInput} (see {@link sendVoxelUpdate}
174
+ * for field units/encoding).
175
+ * @param options - `timeoutMs`: echo wait in milliseconds; defaults to the
176
+ * client's realtime `waitTimeoutMs` (5000).
177
+ * @returns The correlated {@link SpatialNotification} (`VoxelUpdateResponse`).
178
+ * @throws {CrowdyGraphQLError} if the underlying send is rejected.
179
+ * @throws {CrowdyTimeoutError} if the HTTP send leg times out.
180
+ * @throws {CrowdyRealtimeError} on echo timeout
181
+ * (`code === 'UDP_SEQUENCE_TIMEOUT'`) or a matching `GenericErrorResponse`
182
+ * (its `code` is the server's `errorCode`).
183
+ */
25
184
  sendVoxelUpdateAndWait(input: SendVoxelUpdateMutationVariables['input'], options?: {
26
185
  timeoutMs?: number;
27
186
  }): Promise<SpatialNotification>;
187
+ /**
188
+ * Send a spatial voice/audio packet, fanned out to nearby actors as a
189
+ * `ClientAudioNotification`. Fire-and-forget; opens a UDP proxy session
190
+ * automatically. Voice may be gated by a runtime grid permission
191
+ * (`use_voice_chat`) for the region — if the caller lacks it the game server
192
+ * replies asynchronously with a `GenericErrorResponse` (`errorCode`
193
+ * `UNAUTHORIZED`) on {@link subscribe}. The sender receives no success echo.
194
+ *
195
+ * @param input - {@link ClientAudioPacketInput}:
196
+ * - `appId` — owning app id (`BigInt` as a decimal string).
197
+ * - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
198
+ * - `uuid` — 32-ASCII-character source id (typically the player; not
199
+ * RFC-4122).
200
+ * - `audioData` — compressed audio, base64-encoded.
201
+ * - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
202
+ * to 1 for audio packets.
203
+ * - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
204
+ * defaults to 0 (none) for audio packets.
205
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id.
206
+ * @returns `true` when accepted for sending — **not** confirmation of
207
+ * delivery.
208
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
209
+ */
28
210
  sendAudioPacket(input: SendAudioPacketMutationVariables['input']): Promise<boolean>;
211
+ /**
212
+ * Send a voice/audio packet and wait for a response correlated by
213
+ * `sequenceNumber`. **Note:** the server does not echo audio packets back to
214
+ * the sender (only `GenericErrorResponse` failures are correlated), so on
215
+ * success there is usually nothing to resolve and this rejects on timeout —
216
+ * prefer the fire-and-forget {@link sendAudioPacket} unless you specifically
217
+ * want to surface a send error inline. Requires an active {@link subscribe}.
218
+ *
219
+ * @param input - {@link ClientAudioPacketInput} (see {@link sendAudioPacket}).
220
+ * @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
221
+ * realtime `waitTimeoutMs` (5000).
222
+ * @returns The correlated {@link SpatialNotification}, if one is delivered.
223
+ * @throws {CrowdyGraphQLError} if the underlying send is rejected.
224
+ * @throws {CrowdyTimeoutError} if the HTTP send leg times out.
225
+ * @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
226
+ * or a matching `GenericErrorResponse` (its `code` is the server's
227
+ * `errorCode`, e.g. `UNAUTHORIZED` for a missing voice permission).
228
+ */
29
229
  sendAudioPacketAndWait(input: SendAudioPacketMutationVariables['input'], options?: {
30
230
  timeoutMs?: number;
31
231
  }): Promise<SpatialNotification>;
232
+ /**
233
+ * Send a spatial text/chat packet, fanned out to nearby actors as a
234
+ * `ClientTextNotification`. Fire-and-forget; opens a UDP proxy session
235
+ * automatically. The sender receives no success echo; failures arrive
236
+ * asynchronously as `GenericErrorResponse` on {@link subscribe}.
237
+ *
238
+ * @param input - {@link ClientTextPacketInput}:
239
+ * - `appId` — owning app id (`BigInt` as a decimal string).
240
+ * - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
241
+ * - `uuid` — 32-ASCII-character source id (not RFC-4122).
242
+ * - `text` — message content, UTF-8 (sent as plain text, not base64).
243
+ * - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
244
+ * to 8 for text packets.
245
+ * - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
246
+ * defaults to 0 (none) for text packets.
247
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id.
248
+ * @returns `true` when accepted for sending — **not** confirmation of
249
+ * delivery.
250
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
251
+ */
32
252
  sendTextPacket(input: SendTextPacketMutationVariables['input']): Promise<boolean>;
253
+ /**
254
+ * Send a text/chat packet and wait for a response correlated by
255
+ * `sequenceNumber`. **Note:** the server does not echo text packets back to
256
+ * the sender (only `GenericErrorResponse` failures are correlated), so on
257
+ * success there is usually nothing to resolve and this rejects on timeout —
258
+ * prefer the fire-and-forget {@link sendTextPacket} unless you specifically
259
+ * want to surface a send error inline. Requires an active {@link subscribe}.
260
+ *
261
+ * @param input - {@link ClientTextPacketInput} (see {@link sendTextPacket}).
262
+ * @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
263
+ * realtime `waitTimeoutMs` (5000).
264
+ * @returns The correlated {@link SpatialNotification}, if one is delivered.
265
+ * @throws {CrowdyGraphQLError} if the underlying send is rejected.
266
+ * @throws {CrowdyTimeoutError} if the HTTP send leg times out.
267
+ * @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
268
+ * or a matching `GenericErrorResponse` (its `code` is the server's
269
+ * `errorCode`).
270
+ */
33
271
  sendTextPacketAndWait(input: SendTextPacketMutationVariables['input'], options?: {
34
272
  timeoutMs?: number;
35
273
  }): Promise<SpatialNotification>;
274
+ /**
275
+ * Send a custom, app-defined client event for spatial replication to nearby
276
+ * chunks; nearby actors receive it as a `ClientEventNotification`.
277
+ * Fire-and-forget; opens a UDP proxy session automatically. The sender
278
+ * receives no success echo; failures arrive asynchronously as
279
+ * `GenericErrorResponse` on {@link subscribe}.
280
+ *
281
+ * @param input - {@link ClientEventNotificationInput}:
282
+ * - `appId` — owning app id (`BigInt` as a decimal string).
283
+ * - `chunk` — `{ x, y, z }` chunk address (signed int64 decimal strings).
284
+ * - `uuid` — 32-ASCII-character id of the object controlling the event
285
+ * (not RFC-4122).
286
+ * - `eventType` — app-defined event id, a uint16 (0-65535).
287
+ * - `state` — event state blob, base64-encoded; format defined by the event
288
+ * type.
289
+ * - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
290
+ * to 8 for events.
291
+ * - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
292
+ * defaults to 0 (none) for events.
293
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id.
294
+ * @returns `true` when accepted for sending — **not** confirmation the world
295
+ * processed it.
296
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
297
+ */
36
298
  sendClientEvent(input: SendClientEventMutationVariables['input']): Promise<boolean>;
299
+ /**
300
+ * Send a client event and wait for a response correlated by `sequenceNumber`.
301
+ * **Note:** the server does not echo events back to the sender (only
302
+ * `GenericErrorResponse` failures are correlated), so on success there is
303
+ * usually nothing to resolve and this rejects on timeout — prefer the
304
+ * fire-and-forget {@link sendClientEvent} unless you specifically want to
305
+ * surface a send error inline. Requires an active {@link subscribe}.
306
+ *
307
+ * @param input - {@link ClientEventNotificationInput} (see
308
+ * {@link sendClientEvent}).
309
+ * @param options - `timeoutMs`: wait in milliseconds; defaults to the client's
310
+ * realtime `waitTimeoutMs` (5000).
311
+ * @returns The correlated {@link SpatialNotification}, if one is delivered.
312
+ * @throws {CrowdyGraphQLError} if the underlying send is rejected.
313
+ * @throws {CrowdyTimeoutError} if the HTTP send leg times out.
314
+ * @throws {CrowdyRealtimeError} on timeout (`code === 'UDP_SEQUENCE_TIMEOUT'`)
315
+ * or a matching `GenericErrorResponse` (its `code` is the server's
316
+ * `errorCode`).
317
+ */
37
318
  sendClientEventAndWait(input: SendClientEventMutationVariables['input'], options?: {
38
319
  timeoutMs?: number;
39
320
  }): Promise<SpatialNotification>;
@@ -43,6 +324,20 @@ export declare class UdpAPI {
43
324
  * Fire-and-forget: the sender receives no echo, so there is no
44
325
  * `sendSingleActorMessageAndWait` variant. The target receives a
45
326
  * `SingleActorMessageNotification` on its `udpNotifications` subscription.
327
+ *
328
+ * @param input - {@link SingleActorMessageInput}:
329
+ * - `appId` — the destination actor's app id (`BigInt` as a decimal string).
330
+ * - `chunk` — the **destination** actor's current `{ x, y, z }` chunk
331
+ * (signed int64 decimal strings); the sender must know it.
332
+ * - `targetUuid` — the destination actor's id: exactly 32 ASCII characters
333
+ * (not RFC-4122).
334
+ * - `payload` — message body, base64-encoded; opaque to the server (embed
335
+ * the sender identity yourself if needed).
336
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id (used only to
337
+ * correlate a `GenericErrorResponse`).
338
+ * @returns `true` when accepted for sending — **not** confirmation of
339
+ * delivery.
340
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
46
341
  */
47
342
  sendSingleActorMessage(input: SendSingleActorMessageMutationVariables['input']): Promise<boolean>;
48
343
  /**
@@ -51,6 +346,19 @@ export declare class UdpAPI {
51
346
  * `udpNotifications` subscription. Requires the channel `send_messages`
52
347
  * permission; the server drops the message otherwise. Fire-and-forget: the
53
348
  * sender receives no echo.
349
+ *
350
+ * @param input - {@link ChannelMessageInput}:
351
+ * - `channelId` — the channel id (`groups.group_id`) as a `BigInt` decimal
352
+ * string.
353
+ * - `uuid` — the sender's own actor id: exactly 32 ASCII characters (not
354
+ * RFC-4122).
355
+ * - `payload` — message body, base64-encoded; opaque to the server, max
356
+ * 1024 bytes.
357
+ * - `sequenceNumber` — optional uint8 (0-255) correlation id.
358
+ * @returns `true` when accepted for sending — **not** confirmation of
359
+ * delivery; note that a message dropped for a missing `send_messages`
360
+ * permission still returns `true`.
361
+ * @throws {CrowdyGraphQLError} on auth/validation failures.
54
362
  */
55
363
  sendChannelMessage(input: SendChannelMessageMutationVariables['input']): Promise<boolean>;
56
364
  /**
@@ -62,6 +370,34 @@ export declare class UdpAPI {
62
370
  * only delivers that app's spatial notifications and rejects app-agnostic
63
371
  * subscriptions (a single game token reused across apps would otherwise
64
372
  * cross-deliver). Use a separate client per app (sharing the token store).
373
+ *
374
+ * A missing `appId` is rejected by the game-api with a `RealtimeConnectionEvent`
375
+ * (`code === 'APP_ID_REQUIRED'`) delivered to your `connectionEvent` handler,
376
+ * after which the stream ends. Subscribing without a session token throws
377
+ * synchronously instead.
378
+ *
379
+ * @param handlers - {@link UdpNotificationHandlers}: optional per-typename
380
+ * callbacks (`actorUpdate`, `voxelUpdate`, `audio`, `text`, `clientEvent`,
381
+ * `singleActorMessage`, `channelMessage`, `genericError`, `connectionEvent`,
382
+ * etc.) plus `any` (every notification) and `error` (a
383
+ * {@link CrowdyRealtimeError}).
384
+ * @param appId - The app to scope delivery to (`BigInt` as a decimal string).
385
+ * Required.
386
+ * @returns An unsubscribe function that detaches these handlers (and closes
387
+ * the shared WebSocket if it was the last subscription).
388
+ * @throws {CrowdyRealtimeError} `code === 'AUTH_REQUIRED'` if called with no
389
+ * session token. Server-side connection problems (e.g. `APP_ID_REQUIRED`,
390
+ * `UDP_PROXY_CONNECTION_FAILED`) are delivered to the `connectionEvent` /
391
+ * `error` handlers rather than thrown.
392
+ * @example
393
+ * ```ts
394
+ * const unsubscribe = client.udp.subscribe({
395
+ * actorUpdate: (n) => console.log('actor', n.uuid, n.sequenceNumber),
396
+ * genericError: (e) => console.warn('udp error', e.errorCode),
397
+ * }, appId);
398
+ * // later…
399
+ * unsubscribe();
400
+ * ```
65
401
  */
66
402
  subscribe(handlers: UdpNotificationHandlers, appId: string): () => void;
67
403
  private withSequence;
@@ -1 +1 @@
1
- {"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,KAAK,uBAAuB,EAG5B,KAAK,6BAA6B,EAElC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EAErC,KAAK,+BAA+B,EAEpC,KAAK,gCAAgC,EAErC,KAAK,uCAAuC,EAE5C,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D;;;;;;GAMG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;IAJd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAG3C,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,mBAAmB;IAG7B,OAAO,IAAI,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAK9D,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B,gBAAgB,IAAI,OAAO,CAC/B,6BAA6B,CAAC,0BAA0B,CAAC,CAC1D;IAQK,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,cAAc,CAClB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAKb,qBAAqB,CACzB,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAC/C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAOzB,eAAe,CACnB,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC;IAKb,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,EAChD,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;OAMG;IACG,sBAAsB,CAC1B,KAAK,EAAE,uCAAuC,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;;OAMG;IACG,kBAAkB,CACtB,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC;IAKnB;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAIvE,OAAO,CAAC,YAAY;CAQrB"}
1
+ {"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"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"}