@crowdedkingdoms/crowdyjs 18.6.0-dev.1 → 18.8.0-dev.1

package/MIGRATION.md

@@ -120,6 +120,110 @@ super-admin's session). There is no SDK replacement.
 `dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
 `npm run codegen`).
 
+## 18.8.0: builds report the SDK version they compiled against
+
+Additive, with one new floor: **the build documents select `ExecBuild.sdkVersion`, so 18.8.0
+needs ck-api v2.40.2 or later** for `exec.build`, `buildStatus`, `waitForBuild`, `modBuild`,
+`modClientBuild`, `modBuildStatus` and `waitForModBuild` (an older API refuses the selection).
+
+- **`sdkVersion`** on every build: the version of `ckx-sdk` the platform compiled the build
+  against (`crowdy-client-sdk` for a CLIENT half), from the toolchain of the API instance that
+  ran it. The platform points a crate at its own copy of the SDK whatever version the crate
+  names, so this, not your manifest, says what your code was checked against. `null` until the
+  build starts, and for builds from before the platform recorded it. The build log's first line
+  names the same toolchain.
+
+`schema.gql` and the generated types carry cks-game-api `dev`'s SDL at #494.
+
+## 18.7.0: voice helpers, channel audio, opcode 140 on the relay, wide voxels, self-echo, pause and access refusals
+
+Additive, with reads that change for values they used to get wrong (the wide-voxel item) and one
+new floor: **the token mutations (`portal.mintAppToken`, `exchangeCode`, `refresh`) select
+`runtimeGate` and the `udpNotifications` subscription selects `ChannelAudioNotification`, so
+18.7.0 needs the ck-api release after v2.39.0 that carries both** (an older one refuses the
+selections). Channel audio and the voxel echo need Buddy v0.37.0.
+
+- **Voice helpers** (`media/voice-frames.ts`, exported from the package entry): an optional
+  convention for what an audio payload carries. A 10-byte header, little-endian, goes in front of
+  each codec frame: version 1, codec (0 raw, 1 Opus 48 kHz mono, 2 G.711 µ-law 8 kHz), `u16` seq,
+  `u32` timestamp in codec samples (milliseconds for raw), the frame's duration in ms, and flags
+  (bit 0 the first packet after silence, bit 1 the last before it). `encodeVoiceHeader` /
+  `encodeVoicePacket` write it; `decodeVoicePacket` returns `null` for a packet shorter than
+  10 bytes or of another version and never throws. `VoicePacketizer` numbers one sender's frames
+  across the seq and timestamp wraps and sets the flags (`packetize(frame, { last })`, `skip()`
+  for silence). `VoiceJitterBuffer` takes `push(key, packet, nowMs)` per sender key and returns
+  the due frames from `pull(key, nowMs)` / `poll(nowMs)`: in seq order, `targetDelayMs` (60) after
+  a talk spurt's first packet, a gap (`frame: null`) for each one that never came, late packets
+  dropped, at most `maxFrames` (64) a sender, starting over on a talk spurt or `resetAfterMs`
+  (200) of silence. A spurt that starts while the one before still has frames waiting drops
+  them. CrowdyCPP 0.60.0 has the same helpers and replays `test/unit/fixtures/voice-frames.json`.
+  No codec ships: a browser encodes Opus with WebCodecs (the module doc has the settings). A game
+  with a voice format of its own keeps it; positioning a voice stays the game's.
+- **`genericSpatial`.** Opcode 140 (`GENERIC_SPATIAL_1`), an app-defined spatial payload such as
+  CrowdyCPP's `Connection::sendGenericSpatial`, reaches the new `genericSpatial` handler of
+  `udp.subscribe` (and `any`) as a `GenericSpatialNotification`: the spatial header fields and a
+  base64 `payload`. The World Stores bus has a `genericSpatial` key. **Binary relay only**
+  (`realtime: { binaryTransport: true }`): the GraphQL `udpNotifications` union has no member for
+  140, so the proxy drops it and a client on the GraphQL transport never sees one. `UdpNotification`
+  gains the member, so an exhaustive `switch` over `__typename` needs the new case.
+- **`ChunkStore` keeps wide voxel types and other addresses.** Positions and types are the app's
+  signed 16-bit values, which the platform does not check. An edit the 16×16×16 one-byte grid
+  cannot hold (a type outside 0-255, a position outside 0-15) — a realtime update, a hydrated
+  `voxelStates` entry, or a local `setVoxel` — is kept whole in the new `CachedChunk.overlay`
+  (`ChunkOverlayVoxel`: `x`, `y`, `z`, `voxelType`, `state`; keyed by `voxelKey(x, y, z)`), and
+  `voxelTypeAt` / `voxelStateAt` return it. What changes: a type outside 0-255 is no longer stored
+  truncated (300 used to read as 44, -1 as 255); a position outside 0-15 no longer lands on
+  another voxel (`(16, 0, 0)` used to overwrite `(0, 1, 0)`), and reading one returns the overlay's
+  or nothing; and code that walks `chunk.voxels` itself sees 0 where an in-grid voxel's type is in
+  the overlay. The store is a 16×16×16 helper; a game with other addressing reads the raw
+  `voxelUpdate` events and `chunks.get`'s `voxelStates`.
+- **`createGridHostCalls({ voxelBounds })`** sets the positions and types a CLIENT half's
+  `voxel_set` may write, for a world that uses other signed 16-bit values. The default,
+  `DEFAULT_GRID_VOXEL_BOUNDS`, is today's: positions 0-15, types 0-255. Bounds that are not
+  integer ranges within -32768 to 32767 throw `RangeError` when the host calls are created.
+- **Channel audio** (Buddy v0.37.0). `udp.sendChannelAudio({ channelId, uuid, payload,
+  sequenceNumber? })` sends opcode 35 (opcode 17's layout and signing) on the binary relay, else
+  the `sendChannelAudio` mutation; `payload` is base64, at most 1,024 bytes, and the server
+  refuses it with `UNAUTHORIZED` (7) without the channel's `send_voice` and the app's
+  `use_voice_chat`. There is no echo to the sender. Other members' frames arrive as opcode 36,
+  standalone or bundled, as a `ChannelAudioNotification` (`channelId`, `uuid`, `audioData`
+  base64, `sequenceNumber`, `epochMillis`) on the new `channelAudio` handler of `udp.subscribe`
+  (and `any`) and the World Stores bus key `channelAudio`, on the binary relay and on the GraphQL
+  transport alike (the `udpNotifications` subscription selects the union's
+  `ChannelAudioNotification`, so it too needs that ck-api release). `channels.create` /
+  `grids.createChannel` take `membersCanSpeak` (default false: the member role gets
+  `send_voice`); `GridScope.channels` has `sendAudio(channelId, uuid, audioBase64)`;
+  `serializeChannelAudio` is exported. The voice helpers are the payload: see the README.
+- **UDP error 33, `APP_PAUSED`**: the replication server refuses a paused app's sends.
+  `UDP_ERROR_NAMES[33]` and the generated `UdpErrorCode.AppPaused` name it.
+- **Voxel edits are int16 and their state at most 1,024 bytes.** `udp.sendVoxelUpdate` and
+  `ChunkStore.setVoxel` throw `RangeError` (nothing sent) for a position or type outside
+  -32768..32767 or a state over 1,024 bytes (`assertVoxelEdit`, `VOXEL_STATE_MAX_BYTES`); the
+  server answers those with `INVALID_REQUEST` (15). The 0-15 / 0-255 ranges in the docs were
+  never enforced and are gone.
+- **The echo of your own voxel edit.** Buddy v0.37.0 delivers every accepted edit back to its
+  sender as a `VoxelUpdateNotification`. `ChunkStore` records each `setVoxel` (uuid, sequence,
+  voxel) for 10 s and does not apply its echo again, so a local edit fires `onChunkChanged` once;
+  it applies the echo only when another client's edit of the voxel arrived in between (the server
+  ordered yours last) and no newer local edit of it is pending. A game reading `voxelUpdate`
+  itself sees its own edits there now: compare the `uuid` and `sequenceNumber` with the send's.
+- **Pause and access refusals.** `isAppPaused(gate)` reads `AppTokenResponse.runtimeGate` and
+  `GameClientBootstrap.runtimeGate` (`{ status, reason }`; anything but `ACTIVE` is paused; a
+  paused app still mints, so check before entering). `appPausedOf(err)` reads `APP_PAUSED`
+  (`reason`), `accessRefusalOf(err)` `ACCESS_REVOKED` / `ACCESS_SUSPENDED` (`suspendedUntil`) /
+  `ACCESS_NOT_GRANTED`, `actorExistsOf(err)` `ACTOR_EXISTS` (`ownedByCaller`), with their
+  `*_CODE` constants.
+- **New API wraps**: `users.playerProfile(userId)` and `users.playerProfiles(userIds)` (at most
+  `PLAYER_PROFILES_MAX`, 100; `RangeError` above) for public `{ userId, gamertag, disambiguation }`;
+  `users.get` documents that another user's private fields come back null.
+  `appAccess.suspend(appId, userId, until, idempotencyKey?)`, `unsuspend`,
+  `resyncTierGridPermissions` (`manage_access_tiers`); `suspendedUntil` on every access record.
+  `exec.restartType(appId, nodeType)` → `{ nodeType, stopped }` (`manage_compute`);
+  `exec.status` adds `budgetPauseReason`, `maxInstances`, `maxReservedMb`, `instanceLimit`,
+  `instances`, `reservedMb`. `apps.get` / `apps.update` carry `claimOwnerKeys`;
+  `chunks.get` / `getByDistance` carry `voxelStatesTruncated`; `gameClientBootstrap` carries
+  `runtimeGate` and `wildernessWritesOpen`.
+
 ## 18.6.0: the input log
 
 Additive. An app with replay logging on has its client inputs recorded, and `client.inputLog`

package/README.md

@@ -234,7 +234,7 @@ never told about, so a native refresh without it is a re-placement.
 | Sub-client | What it does |
 |---|---|
 | `client.auth` | Sign-in: `login` / `register` (email + password), magic link, social/OIDC. Passwords: `requestPasswordReset` / `resetPassword`, `changePassword`, and `setInitialPassword` for an account created by magic link or a social provider (added in 15.1.0). Log out, and linked identities (`myIdentities`, `linkIdentity`/`unlinkIdentity`). **No dev bypass** — `devLogin` was removed in 15.0.0 and `DEV_AUTH_BYPASS` is gone from every tier. |
-| `client.users` | `me`, `updateGamertag`, profile reads. |
+| `client.users` | `me`, `updateGamertag`, profile reads; `playerProfile` / `playerProfiles` (up to 100) for other players' public `{ userId, gamertag, disambiguation }`. |
 | `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
 | `client.portal` | App-scoped token minting (`mintAppToken`) and the cross-origin PKCE entry flow (`beginEntry` / `handleAuthorizeRequest` / `completeEntry` / `refresh`). |
 | `client.hosting` | Third-party hosting on Crowdy Games (17.2.0): `claim` a slug for an app, `beginPublish` / `completePublish` / `abandonPublish` a built bundle, `setEnabled`; public `game(slug)` / `listed()`. Mutations need an identity session with `manage_apps`. `@crowdedkingdoms/crowdyjs/hosting` exports `publishDirectory(client, { dir, slug })`, the Node helper that does the whole publish for a `dist/`. |
@@ -245,7 +245,7 @@ never told about, so a native refresh without it is a re-placement.
 | `client.teleport` | Teleport requests. |
 | `client.inputLog` | The input log (18.6.0): `sessions(appId)` and `messages(appId, gameTokenId)` read the client inputs recorded for an app with replay logging on (`apps.update(appId, { replayLoggingEnabled: true })`). A player reads their own; `manage_apps` reads every session. Keep paging while `hasNextPage` is true. |
 | `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
-| `client.exec` | **ck-exec:** an app's server code as hubs and spokes. `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `starters` / `build` / `deploy` build and deploy an app (`manage_compute`); `logs`, `instances`, `versions`, `activateVersion` and `setEnabled` operate it; `mod*` are players' mods on grids they own, and `modClient*`, `gridClientMods`, `consentClientMod`, `trustAuthor`, `revokeClientModConsent` and `revokeAuthorTrust` their CLIENT halves. See [ck-exec](#ck-exec). |
+| `client.exec` | **ck-exec:** an app's server code as hubs and spokes. `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `starters` / `build` / `deploy` build and deploy an app (`manage_compute`); `logs`, `instances`, `versions`, `activateVersion`, `setEnabled`, `restartType` and `status` operate it; `mod*` are players' mods on grids they own, and `modClient*`, `gridClientMods`, `consentClientMod`, `trustAuthor`, `revokeClientModConsent` and `revokeAuthorTrust` their CLIENT halves. See [ck-exec](#ck-exec). |
 | `client.playerWallet` | Player spend: balance, ledger, hourly charges, spend caps, card setup, auto-recharge. A ck-exec mod's compute is billed here, to its owner. |
 | `client.marketplace` | Player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`, requests and invites) and studio moderation of player code (admission queue, listing administration, claim policy). Mods publish and install through `client.exec`. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, optimistic revisions, copy-by-value imports, atomic saves. |
@@ -264,7 +264,7 @@ grouped under `client.admin` and mirrored at the top level):
 |---|---|
 | `client.organizations` | Orgs, members, RBAC roles, org API tokens. |
 | `client.apps` | App registry, discovery + routing (`create`, `routeFor`, `marketplace`), visibility, and player-code admission mode / allow-list administration. |
-| `client.appAccess` | Access tiers + per-user grants, and the feature keys a tier grants (`defineFeature`, `grantTierFeature`, `tierFeatures`, …), which a hub checks with the node API's `players.features`. |
+| `client.appAccess` | Access tiers + per-user grants, and the feature keys a tier grants (`defineFeature`, `grantTierFeature`, `tierFeatures`, …), which a hub checks with the node API's `players.features`; timed bans (`suspend`, `unsuspend`) and `resyncTierGridPermissions`. |
 | `client.billing` | Org wallet + per-app spend budgets. |
 | `client.payments` | Payment checkouts (wallet top-ups, plan purchases). |
 | `client.quotas` | Usage quotas at the org/app scope. |
@@ -346,6 +346,10 @@ const unsubscribe = client.udp.subscribe(
     },
     clientEvent: (event) => { /* ... */ },
     serverEvent: (event) => { /* ... */ },
+    genericSpatial: (event) => {
+      // An app-defined spatial payload (opcode 140): binary relay only, see below.
+      console.log(event.uuid, event.payload); // payload is base64
+    },
     singleActorMessage: (event) => {
       // A direct actor-to-actor message addressed to you.
       console.log(event.uuid, event.payload); // payload is base64
@@ -386,6 +390,13 @@ while `AUTH_REQUIRED` / `APP_ID_REQUIRED` must be fixed by the caller first.
 Unsubscribing stops delivery only; call `client.udp.disconnect()` to close the
 UDP proxy session.
 
+`genericSpatial` receives opcode 140 (`GENERIC_SPATIAL_1`), an app-defined spatial payload the
+server fans out without reading — what CrowdyCPP's `Connection::sendGenericSpatial` sends. It
+arrives only on the binary relay (`realtime: { binaryTransport: true }`): the GraphQL
+`udpNotifications` union has no member for it, so the GraphQL proxy drops it and a client on that
+transport never sees one. A World Stores session carries it on its bus too:
+`session.context.on('genericSpatial', …)`.
+
 ### Surviving the loss of an instance (direct connect)
 
 **If your environment uses direct connect, set `realtime.discoveryUrl`.** Under
@@ -450,6 +461,12 @@ with a live actor within `maxDistance` chunks (straight-line distance between
 chunk coordinates) of `chunk` receive it; they get the same `channelMessage`
 notification.
 
+`sendVoxelUpdate` takes the app's signed 16-bit positions and type and a state of
+at most 1,024 bytes (`RangeError` otherwise, nothing sent). Buddy v0.37.0 echoes
+every accepted voxel edit back to its sender as a `voxelUpdate`, so a game reading
+those sees its own edits; World Stores' `ChunkStore` applies that echo once. A
+paused app's sends are refused with UDP error 33, `APP_PAUSED`.
+
 ### Bundled sends on the binary relay
 
 With `realtime: { binaryTransport: true }` the SDK signs each message itself
@@ -477,6 +494,76 @@ await client.udp.sendSingleActorMessage({
 });
 ```
 
+### Voice payloads
+
+`sendAudioPacket` carries whatever bytes it is given, and a game with a voice format of its own
+keeps it. The voice helpers are an optional one that both SDKs share (CrowdyCPP's
+`crowdy/media/voice_frames.hpp`, held to the same cases in `test/unit/fixtures/voice-frames.json`):
+a 10-byte header in front of each codec frame, little-endian — the version (1), the codec (0 raw,
+1 Opus 48 kHz mono, 2 G.711 µ-law 8 kHz), a `u16` seq, a `u32` timestamp in codec samples, the
+frame's duration in milliseconds and two talk-spurt flags (bit 0 the first packet after silence,
+bit 1 the last before it). A reader refuses a packet shorter than the header or of another
+version. `VoicePacketizer` numbers one sender's frames; `VoiceJitterBuffer` puts each sender's
+packets back in order, plays them out 60 ms (`targetDelayMs`) after the first packet of a talk
+spurt arrived, reports a frame that never came as a gap, drops one that arrives after its
+playout time, and holds at most 64 frames a sender.
+
+```ts
+import {
+  VoiceCodec, VoiceJitterBuffer, VoicePacketizer, decodeBase64, encodeBase64,
+} from '@crowdedkingdoms/crowdyjs';
+
+const packetizer = new VoicePacketizer({ codec: VoiceCodec.OPUS, frameMs: 20 });
+// Every 20 ms while the player talks (`opusFrame` from a WebCodecs AudioEncoder):
+await client.udp.sendAudioPacket({
+  appId, chunk, uuid: me.uuid,
+  audioData: encodeBase64(packetizer.packetize(opusFrame, { last: talkKeyReleased })),
+});
+// ...and packetizer.skip() for every 20 ms of silence that is not sent.
+
+const voices = new VoiceJitterBuffer();
+client.udp.subscribe({
+  audio: (n) => voices.push(n.uuid, decodeBase64(n.audioData), performance.now()),
+  actorLeft: (n) => voices.forget(n.uuid),
+}, appId);
+// From the audio clock, at least once a frame:
+for (const slot of voices.poll(performance.now())) {
+  if (slot.gap) conceal(slot.key, slot.frameMs); // the frame never came
+  else play(slot.key, slot.codec, slot.frame!);
+}
+```
+
+The SDK ships no codec. A browser encodes and decodes Opus with WebCodecs (`AudioEncoder` /
+`AudioDecoder`, `codec: 'opus'`, 48 kHz, one channel; check `AudioEncoder.isConfigSupported`
+first) and falls back to G.711 µ-law where it has none; `media/voice-frames.ts` has the settings.
+Where a voice sits in the world (panning, distance attenuation) stays the game's.
+
+#### Channel audio (party and guild voice)
+
+`sendAudioPacket` reaches players near a chunk. `sendChannelAudio` (Buddy v0.37.0) reaches every
+active member of a channel wherever they are: opcode 35 on the binary relay, the
+`sendChannelAudio` mutation otherwise, at most 1,024 payload bytes. The sender needs the channel's
+`send_voice` (`channels.create({ ..., membersCanSpeak: true })` gives it to the member role) and the
+app's `use_voice_chat`; without them the server answers `UNAUTHORIZED` on the subscription. There is
+no echo. Members get a `channelAudio` notification; key the jitter buffer by channel and sender so
+one player in two channels is two streams. It arrives on the binary relay and on the GraphQL
+transport alike.
+
+```ts
+const party = new VoicePacketizer({ codec: VoiceCodec.OPUS, frameMs: 20 });
+await client.udp.sendChannelAudio({
+  channelId, uuid: me.uuid,
+  payload: encodeBase64(party.packetize(opusFrame, { last: talkKeyReleased })),
+});
+
+const partyVoices = new VoiceJitterBuffer();
+client.udp.subscribe({
+  channelAudio: (n) =>
+    partyVoices.push(`${n.channelId}:${n.uuid}`, decodeBase64(n.audioData), performance.now()),
+}, appId);
+// ...poll(performance.now()) from the audio clock as above.
+```
+
 ## World helpers
 
 ```ts
@@ -545,7 +632,9 @@ holds it to rules of its own (18.0.2): `grid_permission_check` answers only for
 the player's four code-permission keys (`GRID_PERMISSION_CHECK_KEYS`) and
 refuses any other key instead of answering false, because a game knows no other
 key for a grid; `voxel_set` takes a voxel inside its chunk (0-15) and a type
-0-255; and a half's spatial and channel sends go out as an actor uuid the page
+0-255, or the ranges the game sets with `createGridHostCalls({ voxelBounds })` for a world
+whose positions and types are other signed 16-bit values (18.7.0); and a half's spatial and
+channel sends go out as an actor uuid the page
 derives for the grid from the one the half names (`clientHalfActorUuid`), so a
 half can never move the player's avatar or speak as another player. The broker
 refuses a call that names its chunk a second way (`chunk`, `chunk_x`, …): route
@@ -614,6 +703,14 @@ another player's realtime voxel update) reaches a reload only through hydration:
 returns it in `voxelStates`, and the bulk load's `voxels` never hold it. The store hydrates when
 it has a `voxelStateCodec`; without one, set `chunks: { hydrateVoxelStates: true }`.
 
+`chunks` is a helper for 16×16×16 chunks with one byte per voxel. Voxel positions and types are
+the app's signed 16-bit values, which the platform does not check: an edit the dense grid cannot
+hold (a type outside 0-255, a position outside 0-15), whether a realtime update, a hydrated
+`voxelStates` entry or a local `setVoxel`, is kept whole in the chunk's `overlay` (keyed by
+`voxelKey(x, y, z)`) instead of being truncated into `voxels`, and `voxelTypeAt` / `voxelStateAt`
+return it (18.7.0). A game with other addressing reads the raw `voxelUpdate` events and
+`chunks.get`'s `voxelStates`.
+
 A chunk write-back the server refuses (a visitor on someone else's plot, a safe zone, a closed
 wilderness) is dropped, not retried; one that fails for a reason that can clear is tried five
 times. Listen with `session.chunks.onWriteBackFailed(...)` to undo or flag the edit (18.0.4).
@@ -986,6 +1083,13 @@ GraphQL errors carry a stable `extensions.code` (e.g. `UNAUTHENTICATED`,
 where applicable, `extensions.remediation` and `extensions.requiredPermission`.
 Branch on `error.extensions?.code` rather than parsing messages.
 
+Readers for the refusals a player should be told about, each `null` for any other error:
+`accessRefusalOf(err)` (`ACCESS_REVOKED`, `ACCESS_SUSPENDED` with `suspendedUntil`,
+`ACCESS_NOT_GRANTED`), `appPausedOf(err)` (`APP_PAUSED`, with `reason`) and `actorExistsOf(err)`
+(`ACTOR_EXISTS`; `ownedByCaller: true` means a retried create of your own actor). A paused app
+still mints tokens: check `isAppPaused(token.runtimeGate)` (or the bootstrap's `runtimeGate`)
+before entering the world.
+
 ## Idempotent retries
 
 Destructive game-client mutations accept an optional **idempotency key**. Pass

package/dist/binary-wire.d.ts

@@ -52,6 +52,8 @@ export declare const WireMessageType: {
     readonly CHANNEL_MESSAGE_REQUEST: 17;
     readonly CHANNEL_MESSAGE_NOTIFICATION: 18;
     readonly CHANNEL_MESSAGE_RANGED_REQUEST: 32;
+    readonly CHANNEL_AUDIO_REQUEST: 35;
+    readonly CHANNEL_AUDIO_NOTIFICATION: 36;
     readonly ACTOR_UPDATE_REQUEST_2: 128;
     readonly ACTOR_UPDATE_RESPONSE_2: 129;
     readonly ACTOR_UPDATE_NOTIFICATION_2: 130;
@@ -64,6 +66,7 @@ export declare const WireMessageType: {
     readonly CLIENT_TEXT_NOTIFICATION_2: 137;
     readonly CLIENT_EVENT_NOTIFICATION_2: 138;
     readonly SERVER_EVENT_NOTIFICATION_2: 139;
+    readonly GENERIC_SPATIAL_1: 140;
     readonly SINGLE_ACTOR_MESSAGE: 142;
     readonly CLIENT_VIDEO_PACKET_2: 143;
     readonly CLIENT_VIDEO_NOTIFICATION_2: 144;
@@ -111,6 +114,23 @@ export interface SpatialSendBase {
 export declare function serializeActorUpdate(ctx: RelaySignContext, input: SpatialSendBase & {
     state: string;
 }): Promise<Uint8Array>;
+/** Most bytes a voxel edit's state may carry; the server refuses longer with INVALID_REQUEST. */
+export declare const VOXEL_STATE_MAX_BYTES = 1024;
+/**
+ * Check a voxel edit before it is sent: positions and type are app-defined
+ * signed 16-bit integers (no narrower range), and the state is at most
+ * {@link VOXEL_STATE_MAX_BYTES} decoded.
+ * @throws {RangeError} naming the field that does not fit.
+ */
+export declare function assertVoxelEdit(input: {
+    voxel: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    voxelType: number;
+    voxelState?: string | null;
+}): void;
 export declare function serializeVoxelUpdate(ctx: RelaySignContext, input: SpatialSendBase & {
     voxel: {
         x: number;
@@ -153,12 +173,20 @@ export declare function serializeSingleActorMessage(ctx: RelaySignContext, input
  * `[1B type=17][8B channelId][32B uuid][2B payloadLen][payload][1B containsAuth]
  *  [32B HMAC][8B gameTokenId][1B seq]` — HMAC over everything before it.
  */
-export declare function serializeChannelMessage(ctx: RelaySignContext, input: {
+export declare function serializeChannelMessage(ctx: RelaySignContext, input: ChannelSendInput): Promise<Uint8Array>;
+/**
+ * CHANNEL_AUDIO_REQUEST (Buddy v0.37.0): opcode 17's layout and signing with
+ * type byte 35. The payload is opaque (at most 1,024 bytes), typically one
+ * {@link VoicePacketizer} packet.
+ */
+export declare function serializeChannelAudio(ctx: RelaySignContext, input: ChannelSendInput): Promise<Uint8Array>;
+/** Input shared by the channel message and channel audio uplinks (`ChannelMessageInput`). */
+export interface ChannelSendInput {
     channelId: string;
     uuid: string;
     payload?: string | null;
     sequenceNumber?: number | null;
-}): Promise<Uint8Array>;
+}
 /** Largest `maxDistance` a ranged channel message may carry (the GraphQL `Int` ceiling). */
 export declare const CHANNEL_RANGED_MAX_DISTANCE = 2147483647;
 /**

package/dist/binary-wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binary-wire.d.ts","sourceRoot":"","sources":["../src/binary-wire.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"binary-wire.d.ts","sourceRoot":"","sources":["../src/binary-wire.ts"],"names":[],"mappings":"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"}

package/dist/binary-wire.js

@@ -89,6 +89,9 @@ export const WireMessageType = {
     // Buddy v0.35.0: a channel publish only members near an origin chunk receive
     // (they get an ordinary CHANNEL_MESSAGE_NOTIFICATION).
     CHANNEL_MESSAGE_RANGED_REQUEST: 32,
+    // Buddy v0.37.0: channel audio, laid out exactly as 17 / 18 with their own type byte.
+    CHANNEL_AUDIO_REQUEST: 35,
+    CHANNEL_AUDIO_NOTIFICATION: 36,
     ACTOR_UPDATE_REQUEST_2: 128,
     ACTOR_UPDATE_RESPONSE_2: 129,
     ACTOR_UPDATE_NOTIFICATION_2: 130,
@@ -101,6 +104,9 @@ export const WireMessageType = {
     CLIENT_TEXT_NOTIFICATION_2: 137,
     CLIENT_EVENT_NOTIFICATION_2: 138,
     SERVER_EVENT_NOTIFICATION_2: 139,
+    // An app-defined spatial payload (CrowdyCPP `Connection::sendGenericSpatial`, a hub's
+    // emit). Parsed on the binary relay only: the GraphQL union has no member for it.
+    GENERIC_SPATIAL_1: 140,
     SINGLE_ACTOR_MESSAGE: 142,
     // Buddy v0.25.0: webcam video pair (audio's shape, payload = one SDK
     // fragment, see media/video-frames.ts) and the server-only actor-left downlink.
@@ -153,6 +159,7 @@ const UDP_ERROR_NAMES = {
     30: 'CANNOT_DELETE_DEFAULT_WORLD_GRID',
     31: 'GRID_HAS_NESTED_CHILDREN',
     32: 'TOKEN_EXPIRED',
+    33: 'APP_PAUSED',
 };
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -252,6 +259,29 @@ export function serializeClientCapabilities(ctx, appId, flags = SDK_CAPABILITIES
 export function serializeActorUpdate(ctx, input) {
     return serializeSpatial(ctx, WireMessageType.ACTOR_UPDATE_REQUEST_2, input.appId, input.chunk, input.distance ?? 8, input.decayRate ?? 1, input.uuid, decodeBase64(input.state ?? ''), input.sequenceNumber ?? 0);
 }
+/** Most bytes a voxel edit's state may carry; the server refuses longer with INVALID_REQUEST. */
+export const VOXEL_STATE_MAX_BYTES = 1024;
+/**
+ * Check a voxel edit before it is sent: positions and type are app-defined
+ * signed 16-bit integers (no narrower range), and the state is at most
+ * {@link VOXEL_STATE_MAX_BYTES} decoded.
+ * @throws {RangeError} naming the field that does not fit.
+ */
+export function assertVoxelEdit(input) {
+    const int16 = (name, v) => {
+        if (!Number.isInteger(v) || v < -32768 || v > 32767) {
+            throw new RangeError(`${name} must be a signed 16-bit integer: ${v}`);
+        }
+    };
+    int16('voxel.x', input.voxel.x);
+    int16('voxel.y', input.voxel.y);
+    int16('voxel.z', input.voxel.z);
+    int16('voxelType', input.voxelType);
+    const stateBytes = input.voxelState ? decodeBase64(input.voxelState).length : 0;
+    if (stateBytes > VOXEL_STATE_MAX_BYTES) {
+        throw new RangeError(`voxelState is ${stateBytes} bytes; at most ${VOXEL_STATE_MAX_BYTES}`);
+    }
+}
 export function serializeVoxelUpdate(ctx, input) {
     const voxelState = decodeBase64(input.voxelState ?? '');
     const payload = new Uint8Array(10 + voxelState.length);
@@ -292,7 +322,18 @@ export function serializeSingleActorMessage(ctx, input) {
  * `[1B type=17][8B channelId][32B uuid][2B payloadLen][payload][1B containsAuth]
  *  [32B HMAC][8B gameTokenId][1B seq]` — HMAC over everything before it.
  */
-export async function serializeChannelMessage(ctx, input) {
+export function serializeChannelMessage(ctx, input) {
+    return serializeChannelFrame(ctx, WireMessageType.CHANNEL_MESSAGE_REQUEST, input);
+}
+/**
+ * CHANNEL_AUDIO_REQUEST (Buddy v0.37.0): opcode 17's layout and signing with
+ * type byte 35. The payload is opaque (at most 1,024 bytes), typically one
+ * {@link VoicePacketizer} packet.
+ */
+export function serializeChannelAudio(ctx, input) {
+    return serializeChannelFrame(ctx, WireMessageType.CHANNEL_AUDIO_REQUEST, input);
+}
+async function serializeChannelFrame(ctx, messageType, input) {
     const payload = input.payload ? decodeBase64(input.payload) : new Uint8Array(0);
     if (payload.length > 1024) {
         throw new Error(`Channel payload exceeds 1024 bytes: ${payload.length}`);
@@ -305,7 +346,7 @@ export async function serializeChannelMessage(ctx, input) {
     const prefix = new Uint8Array(prefixLen);
     const view = new DataView(prefix.buffer);
     let off = 0;
-    view.setUint8(off, WireMessageType.CHANNEL_MESSAGE_REQUEST);
+    view.setUint8(off, messageType);
     off += 1;
     view.setBigUint64(off, BigInt(input.channelId), true);
     off += 8;
@@ -462,7 +503,8 @@ function parseOne(bytes) {
                 'UNKNOWN_ERROR'),
         };
     }
-    if (messageType === WireMessageType.CHANNEL_MESSAGE_NOTIFICATION) {
+    if (messageType === WireMessageType.CHANNEL_MESSAGE_NOTIFICATION ||
+        messageType === WireMessageType.CHANNEL_AUDIO_NOTIFICATION) {
         // [1B type][8B channelId][32B senderUuid][2B payloadLen][payload][8B epochMillis][1B seq]
         if (bytes.length < 1 + 8 + UUID_SIZE + 2)
             return null;
@@ -480,6 +522,16 @@ function parseOne(bytes) {
         const epochMillis = view.getBigUint64(off, true);
         off += 8;
         const sequenceNumber = view.getUint8(off);
+        if (messageType === WireMessageType.CHANNEL_AUDIO_NOTIFICATION) {
+            return {
+                __typename: 'ChannelAudioNotification',
+                channelId: channelId.toString(),
+                uuid,
+                audioData: encodeBase64(payload),
+                sequenceNumber,
+                epochMillis: epochMillis.toString(),
+            };
+        }
         return {
             __typename: 'ChannelMessageNotification',
             channelId: channelId.toString(),
@@ -574,6 +626,12 @@ function parseOne(bytes) {
                 payload: encodeBase64(p.payload),
             };
         }
+        case WireMessageType.GENERIC_SPATIAL_1:
+            return {
+                __typename: 'GenericSpatialNotification',
+                ...spatialCommon(p),
+                payload: encodeBase64(p.payload),
+            };
         default:
             return null;
     }

package/dist/domains/appAccess.d.ts

@@ -1,5 +1,5 @@
 import type { GraphQLClient } from '../client.js';
-import { type DefineAppFeatureInput, type DefineAppFeatureMutation, type AppFeaturesQuery, type GrantTierFeatureInput, type GrantTierFeatureMutation, type TierFeaturesQuery, type AppAccessTiersQuery, type MyAppAccessQuery, type AppUserAccessByAppQuery, type AppUserAccessConnectionQuery, type AppUserAccessConnectionQueryVariables, type RuntimePermissionsQuery, type AppGrantMemberCandidatesQuery, type ClaimFreeAppAccessMutation, type GrantMyAppAccessMutation, type CreateAccessTierMutation, type UpdateAccessTierMutation, type ArchiveAccessTierMutation, type GrantAppAccessMutation, type RevokeAppAccessMutation, type CreateAccessTierInput, type UpdateAccessTierInput, type GrantAppAccessInput } from '../generated/graphql.js';
+import { type SuspendAppAccessMutation, type UnsuspendAppAccessMutation, type DefineAppFeatureInput, type DefineAppFeatureMutation, type AppFeaturesQuery, type GrantTierFeatureInput, type GrantTierFeatureMutation, type TierFeaturesQuery, type AppAccessTiersQuery, type MyAppAccessQuery, type AppUserAccessByAppQuery, type AppUserAccessConnectionQuery, type AppUserAccessConnectionQueryVariables, type RuntimePermissionsQuery, type AppGrantMemberCandidatesQuery, type ClaimFreeAppAccessMutation, type GrantMyAppAccessMutation, type CreateAccessTierMutation, type UpdateAccessTierMutation, type ArchiveAccessTierMutation, type GrantAppAccessMutation, type RevokeAppAccessMutation, type CreateAccessTierInput, type UpdateAccessTierInput, type GrantAppAccessInput } from '../generated/graphql.js';
 /**
  * App access tiers + per-user access grants — exposed as `client.appAccess`
  * (and grouped under `client.admin`).
@@ -137,6 +137,37 @@ export declare class AppAccessAPI {
      * @returns `true` on success.
      */
     revoke(appId: string, userId: string): Promise<RevokeAppAccessMutation['revokeAppAccess']>;
+    /**
+     * Suspend a player's access to an app until `until`: a timed ban that lifts by
+     * itself. Until then their gameplay tokens are refused with `ACCESS_SUSPENDED`
+     * (carrying `suspendedUntil`, see `accessRefusalOf`), and the tokens they hold
+     * for the app are deleted and their realtime sessions ended at once. `until`
+     * must be in the future and at most 365 days away; the player must have an
+     * access record. Requires the `manage_access_tiers` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param userId - Numeric id of the player to suspend.
+     * @param until - When the suspension lapses (a `Date` or ISO-8601 string).
+     * @param idempotencyKey - Optional; a replay with the same key and arguments returns the first result.
+     * @returns The access record, with `suspendedUntil` set.
+     */
+    suspend(appId: string, userId: string, until: Date | string, idempotencyKey?: string): Promise<SuspendAppAccessMutation['suspendAppAccess']>;
+    /**
+     * Lift a player's suspension before it lapses (a no-op for a player who is
+     * not suspended). Requires the `manage_access_tiers` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param userId - Numeric id of the player whose suspension to lift.
+     * @returns The access record, with `suspendedUntil` cleared.
+     */
+    unsuspend(appId: string, userId: string): Promise<UnsuspendAppAccessMutation['unsuspendAppAccess']>;
+    /**
+     * Re-apply every player's tier keys that follow onto the app's world grid and
+     * rebuild the world grid's permissions. Tier changes made through this API
+     * already do it; call it after a change made another way. Requires the
+     * `manage_access_tiers` app permission.
+     */
+    resyncTierGridPermissions(appId: string): Promise<boolean>;
     /**
      * Define (or re-describe) a feature key for an app. Idempotent on `(appId, featureKey)`.
      * Requires the app-admin `manage_apps` permission.

package/dist/domains/appAccess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appAccess.d.ts","sourceRoot":"","sources":["../../src/domains/appAccess.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"appAccess.d.ts","sourceRoot":"","sources":["../../src/domains/appAccess.ts"],"names":[],"mappings":"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"}

package/dist/domains/appAccess.js

@@ -1,4 +1,4 @@
-import { AppAccessTiersDocument, MyAppAccessDocument, AppUserAccessByAppDocument, AppUserAccessConnectionDocument, RuntimePermissionsDocument, AppGrantMemberCandidatesDocument, ClaimFreeAppAccessDocument, GrantMyAppAccessDocument, CreateAccessTierDocument, UpdateAccessTierDocument, ArchiveAccessTierDocument, GrantAppAccessDocument, RevokeAppAccessDocument, DefineAppFeatureDocument, AppFeaturesDocument, GrantTierFeatureDocument, RevokeTierFeatureDocument, TierFeaturesDocument, } from '../generated/graphql.js';
+import { AppAccessTiersDocument, MyAppAccessDocument, AppUserAccessByAppDocument, AppUserAccessConnectionDocument, RuntimePermissionsDocument, AppGrantMemberCandidatesDocument, ClaimFreeAppAccessDocument, GrantMyAppAccessDocument, CreateAccessTierDocument, UpdateAccessTierDocument, ArchiveAccessTierDocument, GrantAppAccessDocument, RevokeAppAccessDocument, SuspendAppAccessDocument, UnsuspendAppAccessDocument, ResyncTierGridPermissionsDocument, DefineAppFeatureDocument, AppFeaturesDocument, GrantTierFeatureDocument, RevokeTierFeatureDocument, TierFeaturesDocument, } from '../generated/graphql.js';
 /**
  * App access tiers + per-user access grants — exposed as `client.appAccess`
  * (and grouped under `client.admin`).
@@ -195,6 +195,54 @@ export class AppAccessAPI {
         });
         return data.revokeAppAccess;
     }
+    /**
+     * Suspend a player's access to an app until `until`: a timed ban that lifts by
+     * itself. Until then their gameplay tokens are refused with `ACCESS_SUSPENDED`
+     * (carrying `suspendedUntil`, see `accessRefusalOf`), and the tokens they hold
+     * for the app are deleted and their realtime sessions ended at once. `until`
+     * must be in the future and at most 365 days away; the player must have an
+     * access record. Requires the `manage_access_tiers` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param userId - Numeric id of the player to suspend.
+     * @param until - When the suspension lapses (a `Date` or ISO-8601 string).
+     * @param idempotencyKey - Optional; a replay with the same key and arguments returns the first result.
+     * @returns The access record, with `suspendedUntil` set.
+     */
+    async suspend(appId, userId, until, idempotencyKey) {
+        const data = await this.api.request(SuspendAppAccessDocument, {
+            appId,
+            userId,
+            until: until instanceof Date ? until.toISOString() : until,
+            idempotencyKey,
+        });
+        return data.suspendAppAccess;
+    }
+    /**
+     * Lift a player's suspension before it lapses (a no-op for a player who is
+     * not suspended). Requires the `manage_access_tiers` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param userId - Numeric id of the player whose suspension to lift.
+     * @returns The access record, with `suspendedUntil` cleared.
+     */
+    async unsuspend(appId, userId) {
+        const data = await this.api.request(UnsuspendAppAccessDocument, {
+            appId,
+            userId,
+        });
+        return data.unsuspendAppAccess;
+    }
+    /**
+     * Re-apply every player's tier keys that follow onto the app's world grid and
+     * rebuild the world grid's permissions. Tier changes made through this API
+     * already do it; call it after a change made another way. Requires the
+     * `manage_access_tiers` app permission.
+     */
+    async resyncTierGridPermissions(appId) {
+        const data = await this.api.request(ResyncTierGridPermissionsDocument, { appId });
+        return data.resyncTierGridPermissions;
+    }
     // -- Tier features -----------------------------------------------------------
     //
     // Feature keys an access tier grants. A ck-exec hub checks a player's with the node API's