@crowdedkingdoms/crowdyjs 18.5.0-dev.1 → 18.7.0-dev.1

package/dist/domains/udp.d.ts

@@ -1,6 +1,6 @@
 import type { GraphQLClient } from '../client.js';
 import type { SubscriptionManager, UdpNotificationHandlers } from '../subscriptions.js';
-import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendVideoPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables, type SendRangedChannelMessageMutationVariables } from '../generated/graphql.js';
+import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendVideoPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables, type SendChannelAudioMutationVariables, type SendRangedChannelMessageMutationVariables } from '../generated/graphql.js';
 import type { RealtimeMetrics } from '../metrics.js';
 import type { SpatialNotification } from '../realtime.js';
 import { type VideoCodec } from '../media/video-frames.js';
@@ -200,10 +200,10 @@ export declare class UdpAPI {
      *     chunk is a 16x16x16 voxel cube.
      *   - `uuid` — 32-ASCII-character actor/source id (not RFC-4122).
      *   - `voxel` — `{ x, y, z }` voxel coordinates within the chunk; each is an
-     *     int16 (-32768 to 32767).
-     *   - `voxelType` — the new voxel type id.
-     *   - `voxelState` — optional voxel state blob, base64-encoded. Omit
-     *     when the voxel has no state; do not send `''`.
+     *     app-defined int16 (-32768 to 32767).
+     *   - `voxelType` — the new voxel type id, an app-defined int16.
+     *   - `voxelState` — optional voxel state blob, base64-encoded, at most
+     *     1,024 bytes decoded. Omit when the voxel has no state; do not send `''`.
      *   - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
      *     to 8 for voxel updates.
      *   - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
@@ -211,6 +211,8 @@ export declare class UdpAPI {
      *   - `sequenceNumber` — optional uint8 (0-255) correlation id.
      * @returns `true` when accepted for sending — **not** confirmation the world
      *   applied the change.
+     * @throws {RangeError} when a position or the type is not an int16, or the
+     *   state is over 1,024 bytes; nothing is sent.
      * @throws {CrowdyGraphQLError} on auth/validation failures.
      */
     sendVoxelUpdate(input: Omit<SendVoxelUpdateMutationVariables['input'], 'voxelState'> & {
@@ -466,6 +468,23 @@ export declare class UdpAPI {
      * @throws {CrowdyGraphQLError} on auth/validation failures.
      */
     sendChannelMessage(input: SendChannelMessageMutationVariables['input']): Promise<boolean>;
+    /**
+     * Send audio to a channel (opcode 35, Buddy v0.37.0): delivered to every
+     * active member of the channel wherever they are (party or guild voice) as
+     * a `channelAudio` notification. The sender receives no echo. Needs the
+     * channel's `send_voice` right (`createChannel({ membersCanSpeak: true })`
+     * gives the default member role it) and the player's `use_voice_chat`;
+     * without either the server answers `UNAUTHORIZED` on `genericError`.
+     * Every member's downlink is billed as egress, so keep voice channels small.
+     *
+     * @param input - {@link ChannelMessageInput}: `channelId`, the sender's own
+     *   32-character actor `uuid`, `payload` (base64, at most 1,024 bytes; one
+     *   `VoicePacketizer` packet with the SDK voice helpers)
+     *   and an optional uint8 `sequenceNumber` for correlating a refusal.
+     * @returns `true` when accepted for sending, not confirmation of delivery.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    sendChannelAudio(input: SendChannelAudioMutationVariables['input']): Promise<boolean>;
     /**
      * Publish a message to a channel that only members near an origin chunk
      * receive (needs ck-api with `sendRangedChannelMessage` and Buddy v0.35.0).
@@ -511,9 +530,9 @@ export declare class UdpAPI {
      *
      * @param handlers - {@link UdpNotificationHandlers}: optional per-typename
      *   callbacks (`actorUpdate`, `voxelUpdate`, `audio`, `text`, `clientEvent`,
-     *   `singleActorMessage`, `channelMessage`, `genericError`, `connectionEvent`,
-     *   etc.) plus `any` (every notification) and `error` (a
-     *   {@link CrowdyRealtimeError}).
+     *   `singleActorMessage`, `channelMessage`, `channelAudio`, `genericError`, `connectionEvent`,
+     *   etc.; `genericSpatial` fires on the binary relay only) plus `any` (every
+     *   notification) and `error` (a {@link CrowdyRealtimeError}).
      * @param appId - The app to scope delivery to (`BigInt` as a decimal string).
      *   Required.
      * @returns An unsubscribe function that detaches these handlers (and closes

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

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

package/dist/domains/udp.js

@@ -1,7 +1,7 @@
-import { ConnectUdpProxyDocument, DisconnectUdpProxyDocument, UdpProxyConnectionStatusDocument, SendActorUpdateDocument, SendVoxelUpdateDocument, SendAudioPacketDocument, SendVideoPacketDocument, SendTextPacketDocument, SendClientEventDocument, SendSingleActorMessageDocument, SendChannelMessageDocument, SendRangedChannelMessageDocument, } from '../generated/graphql.js';
+import { ConnectUdpProxyDocument, DisconnectUdpProxyDocument, UdpProxyConnectionStatusDocument, SendActorUpdateDocument, SendVoxelUpdateDocument, SendAudioPacketDocument, SendVideoPacketDocument, SendTextPacketDocument, SendClientEventDocument, SendSingleActorMessageDocument, SendChannelMessageDocument, SendChannelAudioDocument, SendRangedChannelMessageDocument, } from '../generated/graphql.js';
 import { payloadBytesOf } from '../metrics.js';
 import { SequenceAllocator } from '../utils.js';
-import { serializeActorUpdate, serializeAudioPacket, serializeChannelMessage, serializeClientEvent, serializeRangedChannelMessage, serializeSingleActorMessage, serializeTextPacket, serializeVideoPacket, serializeVoxelUpdate, } from '../binary-wire.js';
+import { serializeActorUpdate, serializeAudioPacket, serializeChannelAudio, serializeChannelMessage, serializeClientEvent, serializeRangedChannelMessage, serializeSingleActorMessage, serializeTextPacket, serializeVideoPacket, serializeVoxelUpdate, assertVoxelEdit, } from '../binary-wire.js';
 import { fragmentFrame } from '../media/video-frames.js';
 import { encodeBase64 } from '../utils.js';
 /**
@@ -308,10 +308,10 @@ export class UdpAPI {
      *     chunk is a 16x16x16 voxel cube.
      *   - `uuid` — 32-ASCII-character actor/source id (not RFC-4122).
      *   - `voxel` — `{ x, y, z }` voxel coordinates within the chunk; each is an
-     *     int16 (-32768 to 32767).
-     *   - `voxelType` — the new voxel type id.
-     *   - `voxelState` — optional voxel state blob, base64-encoded. Omit
-     *     when the voxel has no state; do not send `''`.
+     *     app-defined int16 (-32768 to 32767).
+     *   - `voxelType` — the new voxel type id, an app-defined int16.
+     *   - `voxelState` — optional voxel state blob, base64-encoded, at most
+     *     1,024 bytes decoded. Omit when the voxel has no state; do not send `''`.
      *   - `distance` — replication radius in chunk units, 0-8 (clamped); defaults
      *     to 8 for voxel updates.
      *   - `decayRate` — decay algorithm 0-5 (see {@link sendActorUpdate});
@@ -319,9 +319,12 @@ export class UdpAPI {
      *   - `sequenceNumber` — optional uint8 (0-255) correlation id.
      * @returns `true` when accepted for sending — **not** confirmation the world
      *   applied the change.
+     * @throws {RangeError} when a position or the type is not an int16, or the
+     *   state is over 1,024 bytes; nothing is sent.
      * @throws {CrowdyGraphQLError} on auth/validation failures.
      */
     async sendVoxelUpdate(input) {
+        assertVoxelEdit(input);
         await this.awaitGameplayTokenReady();
         const viaRelay = await this.sendViaRelay((ctx) => serializeVoxelUpdate(ctx, input));
         if (viaRelay !== null) {
@@ -669,6 +672,33 @@ export class UdpAPI {
         this.record('channelMessage', input);
         return data.sendChannelMessage;
     }
+    /**
+     * Send audio to a channel (opcode 35, Buddy v0.37.0): delivered to every
+     * active member of the channel wherever they are (party or guild voice) as
+     * a `channelAudio` notification. The sender receives no echo. Needs the
+     * channel's `send_voice` right (`createChannel({ membersCanSpeak: true })`
+     * gives the default member role it) and the player's `use_voice_chat`;
+     * without either the server answers `UNAUTHORIZED` on `genericError`.
+     * Every member's downlink is billed as egress, so keep voice channels small.
+     *
+     * @param input - {@link ChannelMessageInput}: `channelId`, the sender's own
+     *   32-character actor `uuid`, `payload` (base64, at most 1,024 bytes; one
+     *   `VoicePacketizer` packet with the SDK voice helpers)
+     *   and an optional uint8 `sequenceNumber` for correlating a refusal.
+     * @returns `true` when accepted for sending, not confirmation of delivery.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    async sendChannelAudio(input) {
+        await this.awaitGameplayTokenReady();
+        const viaRelay = await this.sendViaRelay((ctx) => serializeChannelAudio(ctx, input));
+        if (viaRelay !== null) {
+            this.record('channelAudio', input);
+            return viaRelay;
+        }
+        const data = await this.gql.request(SendChannelAudioDocument, { input });
+        this.record('channelAudio', input);
+        return data.sendChannelAudio;
+    }
     /**
      * Publish a message to a channel that only members near an origin chunk
      * receive (needs ck-api with `sendRangedChannelMessage` and Buddy v0.35.0).
@@ -724,9 +754,9 @@ export class UdpAPI {
      *
      * @param handlers - {@link UdpNotificationHandlers}: optional per-typename
      *   callbacks (`actorUpdate`, `voxelUpdate`, `audio`, `text`, `clientEvent`,
-     *   `singleActorMessage`, `channelMessage`, `genericError`, `connectionEvent`,
-     *   etc.) plus `any` (every notification) and `error` (a
-     *   {@link CrowdyRealtimeError}).
+     *   `singleActorMessage`, `channelMessage`, `channelAudio`, `genericError`, `connectionEvent`,
+     *   etc.; `genericSpatial` fires on the binary relay only) plus `any` (every
+     *   notification) and `error` (a {@link CrowdyRealtimeError}).
      * @param appId - The app to scope delivery to (`BigInt` as a decimal string).
      *   Required.
      * @returns An unsubscribe function that detaches these handlers (and closes

package/dist/domains/users.d.ts

@@ -1,5 +1,7 @@
 import type { GraphQLClient } from '../client.js';
-import { type MeQuery, type UpdateGamertagInput, type UpdateGamertagMutation, type UserQuery, type UpdateUserStateMutation, type UpdateUserStateInput, type FreePlayWindowQuery } from '../generated/graphql.js';
+import { type PlayerProfileQuery, type PlayerProfilesQuery, type MeQuery, type UpdateGamertagInput, type UpdateGamertagMutation, type UserQuery, type UpdateUserStateMutation, type UpdateUserStateInput, type FreePlayWindowQuery } from '../generated/graphql.js';
+/** Most ids {@link UsersAPI.playerProfiles} takes in one call. */
+export declare const PLAYER_PROFILES_MAX = 100;
 /**
  * User identity & account management — exposed as `client.users`.
  *
@@ -62,12 +64,31 @@ export declare class UsersAPI {
      */
     freePlayWindow(): Promise<FreePlayWindowQuery['freePlayWindowInfo']>;
     /**
-     * Look up a user by id. Requires a valid session.
+     * Look up a user by id. Requires a valid session. The private fields
+     * (`email`, `state`, `isConfirmed`, the early-access grants, `orgId`,
+     * `externalId`, `userType`, `isSuperAdmin`) come back `null` for anyone but
+     * yourself; for another player's nametag use {@link playerProfile}.
      *
      * @param id - Numeric user id (`BigInt` as a decimal string).
      * @returns The {@link User}, or `null` if no such user.
      */
     get(id: string): Promise<UserQuery['user']>;
+    /**
+     * A player's public profile (`userId`, `gamertag`, `disambiguation`), for
+     * nametags and friends lists. Needs a game token; carries nothing private.
+     *
+     * @param userId - Numeric user id (`BigInt` as a decimal string).
+     * @returns The profile, or `null` when there is no such user.
+     */
+    playerProfile(userId: string): Promise<PlayerProfileQuery['playerProfile']>;
+    /**
+     * Public profiles for up to 100 players in one call (duplicates are read
+     * once; unknown ids are left out).
+     *
+     * @param userIds - Numeric user ids (`BigInt` decimal strings), at most 100.
+     * @throws {RangeError} for more than 100 ids; nothing is sent.
+     */
+    playerProfiles(userIds: string[]): Promise<PlayerProfilesQuery['playerProfiles']>;
     /**
      * Replace the caller's own top-level state blob (base64; `null` clears it).
      * Only ever writes the caller. Requires a valid session.

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

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/domains/users.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAOL,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAEnD;;;;;;;OAOG;IACG,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAKlC;;;;;;;;;;;;;OAaG;IACG,cAAc,CAClB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IAKpD;;;;;;;;;OASG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAKzC;;;;;OAKG;IACG,cAAc,IAAI,OAAO,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;IAK1E;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAKjD;;;;;;OAMG;IACG,WAAW,CACf,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAIvD"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/domains/users.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EASL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAEjC,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAEnD;;;;;;;OAOG;IACG,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAKlC;;;;;;;;;;;;;OAaG;IACG,cAAc,CAClB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IAKpD;;;;;;;;;OASG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAKzC;;;;;OAKG;IACG,cAAc,IAAI,OAAO,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;IAK1E;;;;;;;;OAQG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAKjD;;;;;;OAMG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAK/C;;;;;;OAMG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAWjD;;;;;;OAMG;IACG,WAAW,CACf,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAIvD"}

package/dist/domains/users.js

@@ -1,4 +1,6 @@
-import { MeDocument, UpdateGamertagDocument, DeleteMyAccountDocument, UserDocument, UpdateUserStateDocument, FreePlayWindowDocument, } from '../generated/graphql.js';
+import { MeDocument, UpdateGamertagDocument, DeleteMyAccountDocument, UserDocument, UpdateUserStateDocument, FreePlayWindowDocument, PlayerProfileDocument, PlayerProfilesDocument, } from '../generated/graphql.js';
+/** Most ids {@link UsersAPI.playerProfiles} takes in one call. */
+export const PLAYER_PROFILES_MAX = 100;
 /**
  * User identity & account management — exposed as `client.users`.
  *
@@ -74,7 +76,10 @@ export class UsersAPI {
         return data.freePlayWindowInfo;
     }
     /**
-     * Look up a user by id. Requires a valid session.
+     * Look up a user by id. Requires a valid session. The private fields
+     * (`email`, `state`, `isConfirmed`, the early-access grants, `orgId`,
+     * `externalId`, `userType`, `isSuperAdmin`) come back `null` for anyone but
+     * yourself; for another player's nametag use {@link playerProfile}.
      *
      * @param id - Numeric user id (`BigInt` as a decimal string).
      * @returns The {@link User}, or `null` if no such user.
@@ -83,6 +88,33 @@ export class UsersAPI {
         const data = await this.graphql.request(UserDocument, { id });
         return data.user;
     }
+    /**
+     * A player's public profile (`userId`, `gamertag`, `disambiguation`), for
+     * nametags and friends lists. Needs a game token; carries nothing private.
+     *
+     * @param userId - Numeric user id (`BigInt` as a decimal string).
+     * @returns The profile, or `null` when there is no such user.
+     */
+    async playerProfile(userId) {
+        const data = await this.graphql.request(PlayerProfileDocument, { userId });
+        return data.playerProfile;
+    }
+    /**
+     * Public profiles for up to 100 players in one call (duplicates are read
+     * once; unknown ids are left out).
+     *
+     * @param userIds - Numeric user ids (`BigInt` decimal strings), at most 100.
+     * @throws {RangeError} for more than 100 ids; nothing is sent.
+     */
+    async playerProfiles(userIds) {
+        if (userIds.length > PLAYER_PROFILES_MAX) {
+            throw new RangeError(`playerProfiles takes at most ${PLAYER_PROFILES_MAX} ids: ${userIds.length}`);
+        }
+        if (userIds.length === 0)
+            return [];
+        const data = await this.graphql.request(PlayerProfilesDocument, { userIds });
+        return data.playerProfiles;
+    }
     /**
      * Replace the caller's own top-level state blob (base64; `null` clears it).
      * Only ever writes the caller. Requires a valid session.

package/dist/domains/voxels.d.ts

@@ -14,7 +14,8 @@ import { type ListVoxelsQuery, type ListVoxelsQueryVariables, type ListVoxelUpda
  *
  * Coordinate & encoding conventions:
  * - **Chunk coordinates** are int64 **decimal strings**; **voxel positions**
- *   (`location`) are signed 16-bit ints, `0-15` per axis for in-bounds voxels.
+ *   (`location`) and voxel types are app-defined signed 16-bit ints; an app on
+ *   the 16x16x16 dense grid uses `0-15` per axis and types `0-255`.
  * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
  * - Voxel `state` blobs are **base64-encoded** binary.
  *
@@ -65,8 +66,8 @@ export declare class VoxelsAPI {
      * grids cover the chunk, `update_voxel_data` on a covering grid).
      *
      * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
-     *   local voxel `location` (`0-15` per axis), the `voxelType` to write
-     *   (`0-255`), and an optional base64 `state` blob.
+     *   local voxel `location` and the `voxelType` to write (app-defined
+     *   int16s), and an optional base64 `state` blob (at most 1,024 bytes).
      * @returns The resulting {@link Voxel}.
      * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
      *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.

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

@@ -1 +1 @@
-{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,iCAAiC,EACtC,KAAK,0CAA0C,EAE/C,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKzC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKzE;;;;;;;;;;;;;OAaG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKzD;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,IAAI,EAAE,0CAA0C,GAC/C,OAAO,CAAC,iCAAiC,CAAC,8BAA8B,CAAC,CAAC;IAQ7E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}
+{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,iCAAiC,EACtC,KAAK,0CAA0C,EAE/C,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKzC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKzE;;;;;;;;;;;;;OAaG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKzD;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,IAAI,EAAE,0CAA0C,GAC/C,OAAO,CAAC,iCAAiC,CAAC,8BAA8B,CAAC,CAAC;IAQ7E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}

package/dist/domains/voxels.js

@@ -13,7 +13,8 @@ import { ListVoxelsDocument, ListVoxelUpdatesByDistanceDocument, UpdateVoxelDocu
  *
  * Coordinate & encoding conventions:
  * - **Chunk coordinates** are int64 **decimal strings**; **voxel positions**
- *   (`location`) are signed 16-bit ints, `0-15` per axis for in-bounds voxels.
+ *   (`location`) and voxel types are app-defined signed 16-bit ints; an app on
+ *   the 16x16x16 dense grid uses `0-15` per axis and types `0-255`.
  * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
  * - Voxel `state` blobs are **base64-encoded** binary.
  *
@@ -71,8 +72,8 @@ export class VoxelsAPI {
      * grids cover the chunk, `update_voxel_data` on a covering grid).
      *
      * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
-     *   local voxel `location` (`0-15` per axis), the `voxelType` to write
-     *   (`0-255`), and an optional base64 `state` blob.
+     *   local voxel `location` and the `voxelType` to write (app-defined
+     *   int16s), and an optional base64 `state` blob (at most 1,024 bytes).
      * @returns The resulting {@link Voxel}.
      * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
      *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.

package/dist/errors.d.ts

@@ -247,6 +247,58 @@ export declare class CrowdyUserCodeFaultError extends CrowdyGraphQLError {
  * ```
  */
 export declare function playerFaultOf(value: unknown): CrowdyPlayerFault | null;
+/** `extensions.code` for "an actor with this uuid already exists" (HTTP 409). */
+export declare const ACTOR_EXISTS_CODE = "ACTOR_EXISTS";
+/** `extensions.code` for "this player's access to the app was revoked" (HTTP 403). */
+export declare const ACCESS_REVOKED_CODE = "ACCESS_REVOKED";
+/** `extensions.code` for "this player is suspended from the app until a time" (HTTP 403). */
+export declare const ACCESS_SUSPENDED_CODE = "ACCESS_SUSPENDED";
+/** `extensions.code` for "this player holds no access to the app" (HTTP 403). */
+export declare const ACCESS_NOT_GRANTED_CODE = "ACCESS_NOT_GRANTED";
+/** `extensions.code` for "the app is paused" (HTTP 403); see {@link appPausedOf}. */
+export declare const APP_PAUSED_CODE = "APP_PAUSED";
+/**
+ * Why an app is paused, as `extensions.reason` on `APP_PAUSED` and
+ * `AppRuntimeGate.reason` carry it. Open union: the server may add one.
+ */
+export type AppPauseReason = 'insufficient_funds' | 'spend_cap' | 'subscription_lapsed' | (string & {});
+/**
+ * An `ACTOR_EXISTS` refusal (creating an actor whose uuid is taken), or `null`.
+ * `ownedByCaller` is `extensions.ownedByCaller`: `true` means the actor is
+ * already yours (a retried create; read it rather than failing), `false` that
+ * another player holds the uuid, `null` when the server did not say.
+ */
+export declare function actorExistsOf(value: unknown): {
+    ownedByCaller: boolean | null;
+} | null;
+/** A refusal of the player's own access to an app; see {@link accessRefusalOf}. */
+export interface CrowdyAccessRefusal {
+    code: 'ACCESS_REVOKED' | 'ACCESS_SUSPENDED' | 'ACCESS_NOT_GRANTED';
+    /** `extensions.suspendedUntil` (ISO-8601) on `ACCESS_SUSPENDED`; access returns by itself then. */
+    suspendedUntil?: string;
+}
+/**
+ * An access refusal (`ACCESS_REVOKED`, `ACCESS_SUSPENDED` or `ACCESS_NOT_GRANTED`,
+ * all HTTP 403) from a thrown error or a raw error payload, or `null`. None of
+ * them is fixed by retrying; tell the player.
+ */
+export declare function accessRefusalOf(value: unknown): CrowdyAccessRefusal | null;
+/**
+ * An `APP_PAUSED` refusal (HTTP 403: the app's runtime gate is not ACTIVE), or
+ * `null`. `reason` is `extensions.reason`. Show the player that the world is
+ * paused instead of retrying in a loop.
+ */
+export declare function appPausedOf(value: unknown): {
+    reason: AppPauseReason | null;
+} | null;
+/**
+ * Whether an app's runtime gate (`AppTokenResponse.runtimeGate`,
+ * `GameClientBootstrap.runtimeGate`) says the app is paused: any status but
+ * `ACTIVE`. A missing gate (an older server) reads as not paused.
+ */
+export declare function isAppPaused(gate: {
+    status: string;
+} | null | undefined): boolean;
 /**
  * A network-level failure before any HTTP response was received: DNS failure,
  * TLS error, connection refused, or an aborted `fetch`. Generally retryable

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,kBAAkB;CAKxC;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAKzC;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,yBAAyB,EAAE,CAAC;gBAExC,MAAM,EAAE,yBAAyB,EAAE;IAK/C;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEpD;CACF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB;IAC/D,8DAA8D;IAC9D,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAG9B;IAED;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAGtC;IAED;;;;;OAKG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,oBAAoB,GACpB,0BAA0B,GAC1B,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,sBAAsB,GACtB,iBAAiB,GACjB,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,IAAI,EAAE,eAAe,CAAC;IACtB,2BAA2B;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,qFAAqF;IACrF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,wBAAyB,SAAQ,kBAAkB;IAC9D,gEAAgE;IAChE,IAAI,KAAK,IAAI,iBAAiB,CAQ7B;IAED,0DAA0D;IAC1D,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,2FAA2F;IAC3F,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AA0BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAgCtE;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,KAAK,EAAE,OAAO;CAG3B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM;CAG9B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAKnG;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -243,6 +243,80 @@ export function playerFaultOf(value) {
         return faultFromExtensions(payload.extensions);
     return null;
 }
+/** `extensions.code` for "an actor with this uuid already exists" (HTTP 409). */
+export const ACTOR_EXISTS_CODE = 'ACTOR_EXISTS';
+/** `extensions.code` for "this player's access to the app was revoked" (HTTP 403). */
+export const ACCESS_REVOKED_CODE = 'ACCESS_REVOKED';
+/** `extensions.code` for "this player is suspended from the app until a time" (HTTP 403). */
+export const ACCESS_SUSPENDED_CODE = 'ACCESS_SUSPENDED';
+/** `extensions.code` for "this player holds no access to the app" (HTTP 403). */
+export const ACCESS_NOT_GRANTED_CODE = 'ACCESS_NOT_GRANTED';
+/** `extensions.code` for "the app is paused" (HTTP 403); see {@link appPausedOf}. */
+export const APP_PAUSED_CODE = 'APP_PAUSED';
+/** The first error entry carrying `code`, from an error or a raw payload. */
+function errorWithCode(value, code) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const entries = value instanceof CrowdyGraphQLError
+        ? value.graphqlErrors
+        : [value];
+    return entries.find((entry) => entry?.extensions?.code === code) ?? null;
+}
+/**
+ * An `ACTOR_EXISTS` refusal (creating an actor whose uuid is taken), or `null`.
+ * `ownedByCaller` is `extensions.ownedByCaller`: `true` means the actor is
+ * already yours (a retried create; read it rather than failing), `false` that
+ * another player holds the uuid, `null` when the server did not say.
+ */
+export function actorExistsOf(value) {
+    const entry = errorWithCode(value, ACTOR_EXISTS_CODE);
+    if (!entry)
+        return null;
+    const owned = entry.extensions?.ownedByCaller;
+    return { ownedByCaller: typeof owned === 'boolean' ? owned : null };
+}
+/**
+ * An access refusal (`ACCESS_REVOKED`, `ACCESS_SUSPENDED` or `ACCESS_NOT_GRANTED`,
+ * all HTTP 403) from a thrown error or a raw error payload, or `null`. None of
+ * them is fixed by retrying; tell the player.
+ */
+export function accessRefusalOf(value) {
+    for (const code of [
+        ACCESS_SUSPENDED_CODE,
+        ACCESS_REVOKED_CODE,
+        ACCESS_NOT_GRANTED_CODE,
+    ]) {
+        const entry = errorWithCode(value, code);
+        if (!entry)
+            continue;
+        const refusal = { code };
+        const until = entry.extensions?.suspendedUntil;
+        if (typeof until === 'string' && until.length > 0)
+            refusal.suspendedUntil = until;
+        return refusal;
+    }
+    return null;
+}
+/**
+ * An `APP_PAUSED` refusal (HTTP 403: the app's runtime gate is not ACTIVE), or
+ * `null`. `reason` is `extensions.reason`. Show the player that the world is
+ * paused instead of retrying in a loop.
+ */
+export function appPausedOf(value) {
+    const entry = errorWithCode(value, APP_PAUSED_CODE);
+    if (!entry)
+        return null;
+    const reason = entry.extensions?.reason;
+    return { reason: typeof reason === 'string' && reason.length > 0 ? reason : null };
+}
+/**
+ * Whether an app's runtime gate (`AppTokenResponse.runtimeGate`,
+ * `GameClientBootstrap.runtimeGate`) says the app is paused: any status but
+ * `ACTIVE`. A missing gate (an older server) reads as not paused.
+ */
+export function isAppPaused(gate) {
+    return gate != null && gate.status !== 'ACTIVE';
+}
 /**
  * A network-level failure before any HTTP response was received: DNS failure,
  * TLS error, connection refused, or an aborted `fetch`. Generally retryable