@crowdedkingdomstudios/crowdyjs 5.2.0 → 5.3.0

package/dist/domains/channels.js

@@ -1,92 +1,351 @@
 import { MyChannelsDocument, ChannelsDocument, ChannelDocument, ChannelMembersDocument, ChannelRolesDocument, ChannelPolicyDocument, SetChannelPolicyDocument, CreateChannelDocument, UpdateChannelDocument, DeleteChannelDocument, JoinChannelDocument, RequestToJoinChannelDocument, LeaveChannelDocument, AddChannelMemberDocument, RemoveChannelMemberDocument, SetChannelMemberRolesDocument, CreateChannelRoleDocument, UpdateChannelRoleDocument, DeleteChannelRoleDocument, } from '../generated/graphql.js';
 /**
- * Channels: app-scoped player groups with role-gated messaging, built on the
- * same generic groups subsystem as Teams (group_type='channel'). Channel
- * CRUD/membership runs over the game-api GraphQL endpoint; publishing and
- * receiving channel messages happens over the realtime UDP path (`client.udp`).
+ * Channels: app-scoped, location-independent pub/sub messaging groups on the
+ * **game-api**. Exposed as `client.channels`.
  *
- * Exposed as `client.channels`.
+ * A channel is a named subscriber set with role-gated messaging, built on the
+ * same generic groups subsystem as Teams (`group_type='channel'`). The methods
+ * here manage a channel's lifecycle and configuration — creating channels,
+ * listing/fetching them, managing membership (join/leave/add/remove), roles,
+ * and the per-app channel policy — all over the game-api GraphQL endpoint.
+ *
+ * Realtime message delivery is a **separate** path: publish to a channel with
+ * `client.udp.sendChannelMessage(...)` over UDP. That call requires the
+ * channel's `send_messages` permission and fans the payload out to every
+ * active member (as a `ChannelMessageNotification` on `client.udp`
+ * notifications) rather than chunk-routing it. The methods on this class never
+ * carry message payloads — they only manage who belongs to a channel and what
+ * each member may do.
+ *
+ * `BigInt` ids (`appId`, `groupId`, `userId`, `groupRoleId`) are sent and
+ * received as decimal strings.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`) and the caller must be
+ * entitled to the target app; membership/role/policy mutations additionally
+ * require a specific channel permission (e.g. `manage_group`, `manage_members`,
+ * `manage_roles`) or app-admin (`manage_apps`). Failures throw
+ * {@link CrowdyGraphQLError} carrying a stable `extensions.code` such as
+ * `UNAUTHENTICATED`, `SCOPE_MISSING`, or `FORBIDDEN`.
  */
 export class ChannelsAPI {
     constructor(gql) {
         this.gql = gql;
     }
     // -- Queries --------------------------------------------------------------
+    /**
+     * List the caller's own channels in an app, each with the caller's roles and
+     * effective channel permissions (e.g. whether they hold `send_messages`). Use
+     * this to discover which channels the current user can read and post in.
+     *
+     * @param appId - The app (tenant) to list the caller's channels within, as a
+     *   decimal `BigInt` string.
+     * @returns One {@link GroupMembership} per channel the caller belongs to
+     *   (the channel {@link Group}, the caller's {@link GroupRole}s, their
+     *   effective permission keys, and the join time).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if there is no valid token,
+     *   or `SCOPE_MISSING` / `FORBIDDEN` if the caller isn't entitled to the app.
+     */
     async mine(appId) {
         const data = await this.gql.request(MyChannelsDocument, { appId });
         return data.myChannels;
     }
+    /**
+     * List all active channels in an app — not just the caller's. Use
+     * {@link mine} instead when you only want the channels the caller belongs to.
+     *
+     * @param appId - The app (tenant) whose channels to list, as a decimal
+     *   `BigInt` string.
+     * @returns Every active channel in the app as {@link Group} records.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`, or `SCOPE_MISSING` /
+     *   `FORBIDDEN` if the caller isn't entitled to the app.
+     */
     async list(appId) {
         const data = await this.gql.request(ChannelsDocument, { appId });
         return data.channels;
     }
+    /**
+     * Fetch a single channel by its group id.
+     *
+     * @param groupId - The channel's group id, as a decimal `BigInt` string.
+     * @returns The channel as a {@link Group}.
+     * @throws {CrowdyGraphQLError} if the id does not resolve to a channel (e.g.
+     *   it is a team, or does not exist), or `UNAUTHENTICATED` / `FORBIDDEN` if
+     *   the caller isn't entitled to the app.
+     */
     async get(groupId) {
         const data = await this.gql.request(ChannelDocument, { groupId });
         return data.channel;
     }
+    /**
+     * List a channel's members — its subscriber set, including pending join
+     * requests — each with their membership status and roles.
+     *
+     * @param groupId - The channel whose members to list, as a decimal `BigInt`
+     *   string.
+     * @returns The channel's members as {@link GroupMember} records.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the channel's app.
+     */
     async members(groupId) {
         const data = await this.gql.request(ChannelMembersDocument, { groupId });
         return data.channelMembers;
     }
+    /**
+     * List a channel's roles, including the system `leader` role and any default
+     * `member` role (which typically grants `send_messages`).
+     *
+     * @param groupId - The channel whose roles to list, as a decimal `BigInt`
+     *   string.
+     * @returns The channel's roles as {@link GroupRole} records, each with its
+     *   granted permission keys.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the channel's app.
+     */
     async roles(groupId) {
         const data = await this.gql.request(ChannelRolesDocument, { groupId });
         return data.channelRoles;
     }
+    /**
+     * Read an app's current channel policy: who may create channels and the
+     * default membership policy applied to new channels. Falls back to app
+     * defaults when unset.
+     *
+     * @param appId - The app (tenant) whose channel policy to read, as a decimal
+     *   `BigInt` string.
+     * @returns The effective {@link AppGroupPolicy} for channels in the app
+     *   (creation policy, default membership policy, and any member/group caps).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the app.
+     */
     async policy(appId) {
         const data = await this.gql.request(ChannelPolicyDocument, { appId });
         return data.channelPolicy;
     }
     // -- Channel mutations ----------------------------------------------------
+    /**
+     * Create a channel in an app. Whether the caller may create one is governed
+     * by the per-app channel creation policy (`admin` | `member` | `anyone`).
+     * The caller becomes the owner with a system `leader` role. When
+     * `input.membersCanSend` is true (the default) a default `member` role
+     * granting `send_messages` is created and auto-assigned to joiners (an open
+     * chat channel); when false, only roles you explicitly grant may post (an
+     * announce / read-only channel).
+     *
+     * @param input - {@link CreateChannelInput}: the owning `appId`, the channel
+     *   `name` (max 128 chars, unique per app + type), and optional
+     *   `description`, `membershipPolicy` (`open` | `request` | `invite` |
+     *   `admin`; defaults to the app policy), and `membersCanSend` flag.
+     * @returns The newly created channel as a {@link Group}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. name too long or a
+     *   duplicate name), `FORBIDDEN` if the channel policy disallows creation, or
+     *   `UNAUTHENTICATED`.
+     */
     async create(input) {
         const data = await this.gql.request(CreateChannelDocument, { input });
         return data.createChannel;
     }
+    /**
+     * Update a channel's name, description, and/or membership policy. Only the
+     * fields present on `input` change; omitted fields are left as-is. Requires
+     * the `manage_group` channel permission (app admins bypass).
+     *
+     * @param input - {@link UpdateChannelInput}: the `groupId` plus the fields to
+     *   change — `name` (max 128 chars), `description`, and/or `membershipPolicy`
+     *   (`open` | `request` | `invite` | `admin`).
+     * @returns The updated channel as a {@link Group}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_group`, `BAD_USER_INPUT` on a validation failure, or
+     *   `UNAUTHENTICATED`.
+     */
     async update(input) {
         const data = await this.gql.request(UpdateChannelDocument, { input });
         return data.updateChannel;
     }
+    /**
+     * Delete a channel. Requires the `manage_group` channel permission (app
+     * admins bypass). **Destructive**: cascades to the channel's members and
+     * roles and notifies Buddy servers to tear down message routing for the
+     * channel.
+     *
+     * @param groupId - The channel to delete, as a decimal `BigInt` string.
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_group`, or `UNAUTHENTICATED`.
+     */
     async remove(groupId) {
         const data = await this.gql.request(DeleteChannelDocument, { groupId });
         return data.deleteChannel;
     }
+    /**
+     * Set who may create channels in an app and the default membership policy
+     * for new channels. Requires app-admin (`manage_apps`). Affects future
+     * channel creation only — existing channels are unchanged.
+     *
+     * @param input - {@link SetChannelPolicyInput}: the `appId`, the
+     *   `creationPolicy` (`admin` | `member` | `anyone`), the
+     *   `defaultMembershipPolicy` (`open` | `request` | `invite` | `admin`), and
+     *   optional `maxMembers` / `maxGroupsPerUser` caps (`null` = unlimited).
+     * @returns The updated {@link AppGroupPolicy}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   isn't app-admin, `BAD_USER_INPUT` on an invalid policy value, or
+     *   `UNAUTHENTICATED`.
+     */
     async setPolicy(input) {
         const data = await this.gql.request(SetChannelPolicyDocument, { input });
         return data.setChannelPolicy;
     }
     // -- Membership mutations -------------------------------------------------
+    /**
+     * Join a channel as the caller (subscribe to it). Honors the channel's
+     * membership policy: `open` → active immediately; `request` → pending until
+     * a manager approves; `invite` / `admin` → rejected. On becoming active,
+     * Buddy is notified with the caller's effective send permission so message
+     * routing starts.
+     *
+     * @param groupId - The channel to join, as a decimal `BigInt` string.
+     * @returns The caller's {@link GroupMember} record; its `status` reflects
+     *   `active` vs. `pending`.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` if the membership policy rejects
+     *   the join, or `UNAUTHENTICATED`.
+     */
     async join(groupId) {
         const data = await this.gql.request(JoinChannelDocument, { groupId });
         return data.joinChannel;
     }
+    /**
+     * Request to join a request-only channel, creating a pending membership a
+     * manager can later approve via {@link addMember}. Behaves identically to
+     * {@link join}; it exists as a clearer name for request-policy UIs.
+     *
+     * @param groupId - The request-only channel to request to join, as a decimal
+     *   `BigInt` string.
+     * @returns The caller's pending {@link GroupMember} record.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` if the membership policy rejects
+     *   the request, or `UNAUTHENTICATED`.
+     */
     async requestToJoin(groupId) {
         const data = await this.gql.request(RequestToJoinChannelDocument, { groupId });
         return data.requestToJoinChannel;
     }
+    /**
+     * Leave a channel (unsubscribe the caller). Notifies Buddy to stop routing
+     * messages to the caller.
+     *
+     * @param groupId - The channel to leave, as a decimal `BigInt` string.
+     * @returns `true` if a membership was removed (`false` if the caller wasn't
+     *   a member).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`.
+     */
     async leave(groupId) {
         const data = await this.gql.request(LeaveChannelDocument, { groupId });
         return data.leaveChannel;
     }
+    /**
+     * Add a user to a channel, or approve their pending join request (upserts
+     * the membership to `active`). Requires the `manage_members` channel
+     * permission (app admins bypass). Auto-assigns the channel's default role if
+     * configured and notifies Buddy with the member's effective send permission.
+     *
+     * @param groupId - The channel to add the user to, as a decimal `BigInt`
+     *   string.
+     * @param userId - The user to add or approve, as a decimal `BigInt` string.
+     * @returns The added/approved {@link GroupMember} record.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_members`, or `UNAUTHENTICATED`.
+     */
     async addMember(groupId, userId) {
         const data = await this.gql.request(AddChannelMemberDocument, { groupId, userId });
         return data.addChannelMember;
     }
+    /**
+     * Remove a member from a channel. Requires the `manage_members` channel
+     * permission, except that any member may remove themselves (pass their own
+     * `userId`). Notifies Buddy to stop routing messages to the removed member.
+     *
+     * @param groupId - The channel to remove the user from, as a decimal
+     *   `BigInt` string.
+     * @param userId - The user to remove; may be the caller's own id to
+     *   self-remove. Decimal `BigInt` string.
+     * @returns `true` if a membership was removed.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` when removing
+     *   another member without `manage_members`, or `UNAUTHENTICATED`.
+     */
     async removeMember(groupId, userId) {
         const data = await this.gql.request(RemoveChannelMemberDocument, { groupId, userId });
         return data.removeChannelMember;
     }
+    /**
+     * Replace a member's channel roles with the given set. This is **not
+     * additive** — roles not listed are removed. Requires the `manage_roles`
+     * channel permission (app admins bypass). Re-pushes the member's effective
+     * send permission to Buddy so their ability to post updates immediately.
+     *
+     * @param input - {@link SetMemberRolesInput}: the `groupId`, the target
+     *   `userId`, and `roleIds` — the complete set of channel role ids the member
+     *   should have (ids that are unknown or belong to another group are
+     *   ignored).
+     * @returns The updated {@link GroupMember} record with its new roles.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_roles`, or `UNAUTHENTICATED`.
+     */
     async setMemberRoles(input) {
         const data = await this.gql.request(SetChannelMemberRolesDocument, { input });
         return data.setChannelMemberRoles;
     }
     // -- Role mutations -------------------------------------------------------
+    /**
+     * Create a custom (non-system) channel role granting the given channel
+     * permission keys (e.g. `send_messages` for posting rights). Requires the
+     * `manage_roles` channel permission (app admins bypass).
+     *
+     * @param input - {@link CreateGroupRoleInput}: the `groupId`, the `roleName`
+     *   (max 128 chars, unique within the channel), the `permissions` keys to
+     *   grant (e.g. `send_messages`, `manage_members`; each max 64 chars,
+     *   defaults to none), and an optional `rank` (higher = more senior;
+     *   defaults to 0).
+     * @returns The created {@link GroupRole}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` on an invalid/duplicate name
+     *   or unknown permission key, `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_roles`, or `UNAUTHENTICATED`.
+     */
     async createRole(input) {
         const data = await this.gql.request(CreateChannelRoleDocument, { input });
         return data.createChannelRole;
     }
+    /**
+     * Update a channel role's name, rank, and/or permission keys (system roles
+     * cannot be renamed or re-ranked). When `input.permissions` is supplied it
+     * **replaces** the role's existing keys. Requires the `manage_roles` channel
+     * permission (app admins bypass).
+     *
+     * Note: changing `send_messages` here does not re-push to Buddy until each
+     * affected member's roles are re-applied via {@link setMemberRoles}.
+     *
+     * @param input - {@link UpdateGroupRoleInput}: the `groupRoleId` plus the
+     *   fields to change (`roleName`, `permissions`, `rank`); omitted fields are
+     *   left unchanged.
+     * @returns The updated {@link GroupRole}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` on a validation failure,
+     *   `FORBIDDEN` / `SCOPE_MISSING` if the caller lacks `manage_roles`, or
+     *   `UNAUTHENTICATED`.
+     */
     async updateRole(input) {
         const data = await this.gql.request(UpdateChannelRoleDocument, { input });
         return data.updateChannelRole;
     }
+    /**
+     * Delete a non-system channel role. Requires the `manage_roles` channel
+     * permission (app admins bypass). The system `leader` role cannot be
+     * deleted. **Destructive**: removes the role from any members that held it.
+     *
+     * @param groupRoleId - The channel role to delete (must be a non-system
+     *   role), as a decimal `BigInt` string.
+     * @returns `true` if a role was deleted.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` / `SCOPE_MISSING` if the caller
+     *   lacks `manage_roles`, `BAD_USER_INPUT` if targeting a system role, or
+     *   `UNAUTHENTICATED`.
+     */
     async deleteRole(groupRoleId) {
         const data = await this.gql.request(DeleteChannelRoleDocument, { groupRoleId });
         return data.deleteChannelRole;

package/dist/domains/chunks.d.ts

@@ -1,20 +1,133 @@
 import type { GraphQLClient } from '../client.js';
 import { type GetChunkQuery, type GetChunkQueryVariables, type GetChunkLodsQuery, type GetChunkLodsQueryVariables, type GetChunksByDistanceQuery, type GetChunksByDistanceQueryVariables, type GetVoxelListQuery, type GetVoxelListQueryVariables, type UpdateChunkMutation, type UpdateChunkMutationVariables, type UpdateChunkStateMutation, type UpdateChunkStateMutationVariables, type UpdateChunkLodsMutation, type UpdateChunkLodsMutationVariables } from '../generated/graphql.js';
 /**
- * Chunk-level queries and mutations: lookup, LODs, distance scans,
- * voxel lists, and chunk state/LOD updates.
- *
+ * Chunk-level reads and writes for an app's voxel world on the **game-api**.
  * Exposed as `client.chunks`.
+ *
+ * A "chunk" is a persisted 16×16×16-voxel cube (4096 voxels) of an app's world.
+ * It holds the packed voxel-type grid (`voxels`), sparse per-voxel state
+ * overrides (`voxelStates`), an optional opaque chunk-level state blob
+ * (`chunkState`), and level-of-detail meshes (`lods`). Use this API for
+ * authoritative world persistence and bulk region loads; for high-frequency,
+ * per-voxel realtime edits prefer the UDP path
+ * (`client.udp.sendVoxelUpdate(...)`), which is far cheaper per update.
+ *
+ * Coordinate & encoding conventions used throughout:
+ * - **Chunk coordinates** (`coordinates.x/y/z`) are int64 **decimal strings**;
+ *   `+1` on an axis is one chunk (16 voxels) further along it.
+ * - **Voxel positions** (`location` / `voxelCoord`) are signed 16-bit ints,
+ *   `0-15` per axis for in-bounds voxels.
+ * - Binary blobs — the dense `voxels` grid (exactly 4096 bytes once decoded),
+ *   per-voxel `state`, `chunkState`, and LOD `data` — are **base64-encoded**.
+ * - `appId` is a `BigInt` sent and received as a decimal string.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`); an app-scoped token may only
+ * touch its own app, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED` / `FORBIDDEN`). The two privileged writes
+ * ({@link ChunksAPI.updateState}, {@link ChunksAPI.updateLods}) additionally
+ * require the `manage_apps` permission on the owning org
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
  */
 export declare class ChunksAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * Fetch a single chunk — its base64 voxel grid, per-voxel states, chunk-level
+     * state and LODs — by app id and chunk coordinates. Read-only. Use the input's
+     * LOD options (`requestedLodLevels` / `includeAllLods`) to limit which LODs
+     * come back.
+     *
+     * @param input - {@link GetChunkInput}: `appId` (decimal string), chunk
+     *   `coordinates` (int64 decimal strings), and optional LOD filtering.
+     * @returns The {@link Chunk}, or `null` if no chunk exists at those
+     *   coordinates. Binary fields (`voxels`, `chunkState`, per-voxel/LOD `data`)
+     *   are base64-encoded.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`, or `FORBIDDEN` if an
+     *   app-scoped token is used against a different app.
+     */
     get(input: GetChunkQueryVariables['input']): Promise<GetChunkQuery['getChunk']>;
+    /**
+     * Fetch only the requested level-of-detail (LOD) meshes for one chunk —
+     * cheaper than {@link ChunksAPI.get} when you only need LODs. Read-only.
+     *
+     * @param input - {@link GetChunkLodsInput}: `appId`, chunk `coordinates`, and
+     *   `lodLevels` (the LOD levels to return; each `>= 0`, where `0` is finest).
+     * @returns A {@link ChunkLodsResponse} (chunk identity plus the matching
+     *   `lods`, each carrying base64 `data`), or `null` if the chunk does not
+     *   exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     getLods(input: GetChunkLodsQueryVariables['input']): Promise<GetChunkLodsQuery['getChunkLods']>;
+    /**
+     * Return all chunks for an app within a cubic (Chebyshev-distance) radius of a
+     * center chunk, paginated — the cube spans center ± `maxDistance` chunks on
+     * each axis (a `(2·maxDistance+1)³` cube). Use this for bulk region loads; use
+     * {@link ChunksAPI.get} for a single chunk. Read-only.
+     *
+     * @param input - {@link GetChunksByDistanceInput}: `appId`, `centerCoordinate`
+     *   (int64 decimal strings), `maxDistance` (in chunk units, integer `1-8`),
+     *   and optional `limit` (max chunks, default 1000) / `skip` (default 0)
+     *   pagination.
+     * @returns A {@link ChunksByDistanceResponse}: the matching `chunks` plus an
+     *   echo of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
     byDistance(input: GetChunksByDistanceQueryVariables['input']): Promise<GetChunksByDistanceQuery['getChunksByDistance']>;
+    /**
+     * List every recorded voxel edit (the `voxel_updates` log) for a single chunk,
+     * newest first. Use {@link ChunksAPI.get} instead when you want the packed
+     * voxel grid rather than the individual edit log. Read-only.
+     *
+     * @param input - {@link GetVoxelListInput}: `appId` and chunk `coordinates`.
+     * @returns A {@link ChunkVoxelResponse}: the chunk address plus its
+     *   {@link Voxel} edits (each `state` blob base64-encoded), newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     voxelList(input: GetVoxelListQueryVariables['input']): Promise<GetVoxelListQuery['getVoxelList']>;
+    /**
+     * Create or replace a chunk's dense voxel grid and/or per-voxel states for the
+     * given app and coordinates, recording each provided voxel state as an
+     * individual voxel update and asynchronously uploading the chunk to the CDN.
+     * **Writes world state.** Leaves `chunkState` and LODs untouched.
+     *
+     * @param input - {@link ChunkUpdateInput}: `appId`, `coordinates`, an optional
+     *   base64 `voxels` grid (the decoded buffer must be exactly 4096 bytes — one
+     *   voxel-type byte `0-255` per voxel, indexed `x + y*16 + z*256`), and
+     *   optional `voxelStates` overrides.
+     * @returns The updated {@link Chunk}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. a `voxels` buffer that
+     *   isn't 4096 bytes), `UNAUTHENTICATED`, or `FORBIDDEN` if an app-scoped token
+     *   targets another app.
+     */
     update(input: UpdateChunkMutationVariables['input']): Promise<UpdateChunkMutation['updateChunk']>;
+    /**
+     * Upsert **only** the opaque base64 chunk-level state blob for a chunk,
+     * preserving its voxels, per-voxel states and LODs. **Writes world state.**
+     * Privileged: requires the `manage_apps` permission on the org that owns
+     * `input.appId` (super admins bypass).
+     *
+     * @param input - {@link UpdateChunkStateInput}: `appId`, `coordinates`, and the
+     *   base64-encoded `chunkState` blob (omit/null to store none).
+     * @returns The updated {@link Chunk}, or `null` if it could not be written.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `manage_apps`), or `UNAUTHENTICATED`.
+     */
     updateState(input: UpdateChunkStateMutationVariables['input']): Promise<UpdateChunkStateMutation['updateChunkState']>;
+    /**
+     * Replace the entire level-of-detail (LOD) set for a chunk, preserving its
+     * voxels, per-voxel states, chunk state and owner. **Writes world state.**
+     * Privileged: requires the `manage_apps` permission on the org that owns
+     * `input.appId` (super admins bypass).
+     *
+     * @param input - {@link UpdateChunkLodsInput}: `appId`, `coordinates`, and the
+     *   full `lods` set (each entry a `level` `>= 0` plus base64 `data`); this
+     *   REPLACES any existing LODs.
+     * @returns The updated {@link Chunk}, or `null` if it could not be written.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `manage_apps`), or `UNAUTHENTICATED`.
+     */
     updateLods(input: UpdateChunkLodsMutationVariables['input']): Promise<UpdateChunkLodsMutation['updateChunkLods']>;
 }
 //# sourceMappingURL=chunks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/domains/chunks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EAEtC,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EAEtC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACtC,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEhC,GAAG,CACP,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACrC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAK/B,OAAO,CACX,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAKvC,UAAU,CACd,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;IAKrD,SAAS,CACb,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAKvC,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAKxC,WAAW,CACf,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAKlD,UAAU,CACd,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAIvD"}
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/domains/chunks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EAEtC,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EAEtC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACtC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;;;;OAaG;IACG,GAAG,CACP,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACrC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAKrC;;;;;;;;;;OAUG;IACG,OAAO,CACX,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAK7C;;;;;;;;;;;;;;OAcG;IACG,UAAU,CACd,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;IAK3D;;;;;;;;;OASG;IACG,SAAS,CACb,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAK7C;;;;;;;;;;;;;;OAcG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;OAWG;IACG,WAAW,CACf,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAKxD;;;;;;;;;;;;OAYG;IACG,UAAU,CACd,KAAK,EAAE,gCAAgC,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAIvD"}

package/dist/domains/chunks.js

@@ -1,38 +1,151 @@
 import { GetChunkDocument, GetChunkLodsDocument, GetChunksByDistanceDocument, GetVoxelListDocument, UpdateChunkDocument, UpdateChunkStateDocument, UpdateChunkLodsDocument, } from '../generated/graphql.js';
 /**
- * Chunk-level queries and mutations: lookup, LODs, distance scans,
- * voxel lists, and chunk state/LOD updates.
- *
+ * Chunk-level reads and writes for an app's voxel world on the **game-api**.
  * Exposed as `client.chunks`.
+ *
+ * A "chunk" is a persisted 16×16×16-voxel cube (4096 voxels) of an app's world.
+ * It holds the packed voxel-type grid (`voxels`), sparse per-voxel state
+ * overrides (`voxelStates`), an optional opaque chunk-level state blob
+ * (`chunkState`), and level-of-detail meshes (`lods`). Use this API for
+ * authoritative world persistence and bulk region loads; for high-frequency,
+ * per-voxel realtime edits prefer the UDP path
+ * (`client.udp.sendVoxelUpdate(...)`), which is far cheaper per update.
+ *
+ * Coordinate & encoding conventions used throughout:
+ * - **Chunk coordinates** (`coordinates.x/y/z`) are int64 **decimal strings**;
+ *   `+1` on an axis is one chunk (16 voxels) further along it.
+ * - **Voxel positions** (`location` / `voxelCoord`) are signed 16-bit ints,
+ *   `0-15` per axis for in-bounds voxels.
+ * - Binary blobs — the dense `voxels` grid (exactly 4096 bytes once decoded),
+ *   per-voxel `state`, `chunkState`, and LOD `data` — are **base64-encoded**.
+ * - `appId` is a `BigInt` sent and received as a decimal string.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`); an app-scoped token may only
+ * touch its own app, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED` / `FORBIDDEN`). The two privileged writes
+ * ({@link ChunksAPI.updateState}, {@link ChunksAPI.updateLods}) additionally
+ * require the `manage_apps` permission on the owning org
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
  */
 export class ChunksAPI {
     constructor(gql) {
         this.gql = gql;
     }
+    /**
+     * Fetch a single chunk — its base64 voxel grid, per-voxel states, chunk-level
+     * state and LODs — by app id and chunk coordinates. Read-only. Use the input's
+     * LOD options (`requestedLodLevels` / `includeAllLods`) to limit which LODs
+     * come back.
+     *
+     * @param input - {@link GetChunkInput}: `appId` (decimal string), chunk
+     *   `coordinates` (int64 decimal strings), and optional LOD filtering.
+     * @returns The {@link Chunk}, or `null` if no chunk exists at those
+     *   coordinates. Binary fields (`voxels`, `chunkState`, per-voxel/LOD `data`)
+     *   are base64-encoded.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`, or `FORBIDDEN` if an
+     *   app-scoped token is used against a different app.
+     */
     async get(input) {
         const data = await this.gql.request(GetChunkDocument, { input });
         return data.getChunk;
     }
+    /**
+     * Fetch only the requested level-of-detail (LOD) meshes for one chunk —
+     * cheaper than {@link ChunksAPI.get} when you only need LODs. Read-only.
+     *
+     * @param input - {@link GetChunkLodsInput}: `appId`, chunk `coordinates`, and
+     *   `lodLevels` (the LOD levels to return; each `>= 0`, where `0` is finest).
+     * @returns A {@link ChunkLodsResponse} (chunk identity plus the matching
+     *   `lods`, each carrying base64 `data`), or `null` if the chunk does not
+     *   exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     async getLods(input) {
         const data = await this.gql.request(GetChunkLodsDocument, { input });
         return data.getChunkLods;
     }
+    /**
+     * Return all chunks for an app within a cubic (Chebyshev-distance) radius of a
+     * center chunk, paginated — the cube spans center ± `maxDistance` chunks on
+     * each axis (a `(2·maxDistance+1)³` cube). Use this for bulk region loads; use
+     * {@link ChunksAPI.get} for a single chunk. Read-only.
+     *
+     * @param input - {@link GetChunksByDistanceInput}: `appId`, `centerCoordinate`
+     *   (int64 decimal strings), `maxDistance` (in chunk units, integer `1-8`),
+     *   and optional `limit` (max chunks, default 1000) / `skip` (default 0)
+     *   pagination.
+     * @returns A {@link ChunksByDistanceResponse}: the matching `chunks` plus an
+     *   echo of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
     async byDistance(input) {
         const data = await this.gql.request(GetChunksByDistanceDocument, { input });
         return data.getChunksByDistance;
     }
+    /**
+     * List every recorded voxel edit (the `voxel_updates` log) for a single chunk,
+     * newest first. Use {@link ChunksAPI.get} instead when you want the packed
+     * voxel grid rather than the individual edit log. Read-only.
+     *
+     * @param input - {@link GetVoxelListInput}: `appId` and chunk `coordinates`.
+     * @returns A {@link ChunkVoxelResponse}: the chunk address plus its
+     *   {@link Voxel} edits (each `state` blob base64-encoded), newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     async voxelList(input) {
         const data = await this.gql.request(GetVoxelListDocument, { input });
         return data.getVoxelList;
     }
+    /**
+     * Create or replace a chunk's dense voxel grid and/or per-voxel states for the
+     * given app and coordinates, recording each provided voxel state as an
+     * individual voxel update and asynchronously uploading the chunk to the CDN.
+     * **Writes world state.** Leaves `chunkState` and LODs untouched.
+     *
+     * @param input - {@link ChunkUpdateInput}: `appId`, `coordinates`, an optional
+     *   base64 `voxels` grid (the decoded buffer must be exactly 4096 bytes — one
+     *   voxel-type byte `0-255` per voxel, indexed `x + y*16 + z*256`), and
+     *   optional `voxelStates` overrides.
+     * @returns The updated {@link Chunk}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. a `voxels` buffer that
+     *   isn't 4096 bytes), `UNAUTHENTICATED`, or `FORBIDDEN` if an app-scoped token
+     *   targets another app.
+     */
     async update(input) {
         const data = await this.gql.request(UpdateChunkDocument, { input });
         return data.updateChunk;
     }
+    /**
+     * Upsert **only** the opaque base64 chunk-level state blob for a chunk,
+     * preserving its voxels, per-voxel states and LODs. **Writes world state.**
+     * Privileged: requires the `manage_apps` permission on the org that owns
+     * `input.appId` (super admins bypass).
+     *
+     * @param input - {@link UpdateChunkStateInput}: `appId`, `coordinates`, and the
+     *   base64-encoded `chunkState` blob (omit/null to store none).
+     * @returns The updated {@link Chunk}, or `null` if it could not be written.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `manage_apps`), or `UNAUTHENTICATED`.
+     */
     async updateState(input) {
         const data = await this.gql.request(UpdateChunkStateDocument, { input });
         return data.updateChunkState;
     }
+    /**
+     * Replace the entire level-of-detail (LOD) set for a chunk, preserving its
+     * voxels, per-voxel states, chunk state and owner. **Writes world state.**
+     * Privileged: requires the `manage_apps` permission on the org that owns
+     * `input.appId` (super admins bypass).
+     *
+     * @param input - {@link UpdateChunkLodsInput}: `appId`, `coordinates`, and the
+     *   full `lods` set (each entry a `level` `>= 0` plus base64 `data`); this
+     *   REPLACES any existing LODs.
+     * @returns The updated {@link Chunk}, or `null` if it could not be written.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `manage_apps`), or `UNAUTHENTICATED`.
+     */
     async updateLods(input) {
         const data = await this.gql.request(UpdateChunkLodsDocument, { input });
         return data.updateChunkLods;