@crowdedkingdoms/crowdyjs 1.0.0

package/dist/domains/users.d.ts

@@ -0,0 +1,147 @@
+import type { GraphQLClient } from '../client.js';
+import { type MeQuery, type UpdateGamertagInput, type UpdateGamertagMutation, type UserQuery, type UsersPaginatedQuery, type UsersPaginatedQueryVariables, type UsersConnectionQuery, type UsersConnectionQueryVariables, type SetSuperAdminMutation, type SetOperatorMutation, type SetEarlyAccessOverrideMutation, type UpdateUserTypeMutation, type ForceLogoutUserMutation, type UpdateUserStateMutation, type UpdateUserStateInput, type FreePlayWindowQuery } from '../generated/graphql.js';
+/**
+ * User identity & account management — exposed as `client.users`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`). After
+ * the database split the users table is management-owned, so game-api no longer
+ * exposes these identity mutations — calling them against a game-api endpoint
+ * throws {@link CrowdyGraphQLError} with `FORBIDDEN`, directing you to the
+ * management API. Only the read/identity surface a game client realistically
+ * needs lives here; super-admin / operator screens use the management UI
+ * directly rather than the SDK.
+ *
+ * Every method needs a valid session (a bearer token set by
+ * `client.auth.login()` / `register()` or `client.setToken()`); without one the
+ * server returns `UNAUTHENTICATED` — except {@link me}, which resolves to
+ * `null`. `BigInt` ids such as `userId` and `orgId` are decimal strings.
+ */
+export declare class UsersAPI {
+    private readonly graphql;
+    constructor(graphql: GraphQLClient);
+    /**
+     * Validate the current bearer token and return the authenticated user record.
+     * Handy for restoring a session on SDK init.
+     *
+     * @returns The {@link User}, or `null` if the token is missing, expired, or
+     *   revoked (an invalid token resolves to `null` rather than throwing).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    me(): Promise<MeQuery['me']>;
+    /**
+     * Set the authenticated user's gamertag and disambiguation (and append a
+     * gamertag-history row). Only ever updates the caller. Requires a valid
+     * session.
+     *
+     * @param input - {@link UpdateGamertagInput}: the new `gamertag` (max 64
+     *   characters) and `disambiguation` (max 128 characters); the pair must be
+     *   unique across the platform.
+     * @returns The updated {@link User} (its `userId`, `gamertag`,
+     *   `disambiguation`, and `userType`).
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the gamertag +
+     *   disambiguation pair is already taken, `UNAUTHENTICATED` without a session,
+     *   or `FORBIDDEN` when called against game-api (call the management API).
+     */
+    updateGamertag(input: UpdateGamertagInput): Promise<UpdateGamertagMutation['updateGamertag']>;
+    /**
+     * **Destructive, self-service** soft-delete of the caller's **own** account:
+     * anonymizes PII and revokes all sessions. Wallet, voxel, and donation history
+     * stay intact via foreign keys. Acts only on the caller (no target argument).
+     * Requires a valid session.
+     *
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a session, or
+     *   `FORBIDDEN` when called against game-api (call the management API).
+     */
+    deleteMyAccount(): Promise<boolean>;
+    /**
+     * Report whether a free-play window is currently active and when the next one
+     * starts. **Public** — no session required.
+     *
+     * @returns The {@link FreePlayWindowInfo}.
+     */
+    freePlayWindow(): Promise<FreePlayWindowQuery['freePlayWindowInfo']>;
+    /**
+     * Look up any user by id. **Super-admin only** (regular callers can only read
+     * their own profile via {@link me}).
+     *
+     * @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']>;
+    /**
+     * Search/list users with offset pagination. **Super-admin only.**
+     *
+     * @param opts - Optional `query` (prefix match over email/gamertag/id) and
+     *   `limit` / `offset`.
+     * @returns A page of users.
+     * @remarks Prefer {@link listConnection} (Relay cursor pagination) for large
+     *   result sets; the offset args here are deprecated server-side.
+     */
+    paginated(opts?: {
+        query?: UsersPaginatedQueryVariables['query'];
+        limit?: UsersPaginatedQueryVariables['limit'];
+        offset?: UsersPaginatedQueryVariables['offset'];
+    }): Promise<UsersPaginatedQuery['usersPaginated']>;
+    /**
+     * Relay-style cursor pagination over users — the preferred alternative to
+     * {@link paginated}. **Super-admin only.** Page with `first` plus the previous
+     * page's `pageInfo.endCursor` as `after`. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first`, `after`, and `query`.
+     * @returns A {@link UsersConnection}.
+     */
+    listConnection(args?: UsersConnectionQueryVariables): Promise<UsersConnectionQuery['usersConnection']>;
+    /**
+     * Grant or revoke the platform `is_super_admin` flag on a user. **Super-admin
+     * only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant, `false` to revoke.
+     * @returns The updated user's `userId` + `isSuperAdmin`.
+     */
+    setSuperAdmin(userId: string, value: boolean): Promise<SetSuperAdminMutation['setSuperAdmin']>;
+    /**
+     * Grant or revoke the platform `is_operator` flag (control-plane access) on a
+     * user. **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant, `false` to revoke.
+     * @returns The updated user's `userId` + `isOperator`.
+     */
+    setOperator(userId: string, value: boolean): Promise<SetOperatorMutation['setOperator']>;
+    /**
+     * Force an early-access override on a user (bypasses the early-access gate).
+     * **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant the override, `false` to clear it.
+     * @returns The updated user's `userId` + `grantEarlyAccessOverride`.
+     */
+    setEarlyAccessOverride(userId: string, value: boolean): Promise<SetEarlyAccessOverrideMutation['setEarlyAccessOverride']>;
+    /**
+     * Set a user's `user_type`. **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - The new user type string.
+     * @returns The updated user's `userId` + `userType`.
+     */
+    updateType(userId: string, value: string): Promise<UpdateUserTypeMutation['updateUserType']>;
+    /**
+     * Revoke all of a user's sessions (force logout everywhere). **Super-admin
+     * only.**
+     *
+     * @param userId - Target user id.
+     * @returns `true` on success.
+     */
+    forceLogout(userId: string): Promise<ForceLogoutUserMutation['forceLogoutUser']>;
+    /**
+     * Replace a user's top-level state blob. **Super-admin only.**
+     *
+     * @param input - {@link UpdateUserStateInput} (`userId` + base64 `state`).
+     * @returns The updated user's `userId` + `state`.
+     */
+    updateState(input: UpdateUserStateInput): Promise<UpdateUserStateMutation['updateUserState']>;
+}
+//# sourceMappingURL=users.d.ts.map

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

@@ -0,0 +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,EAcL,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,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;;;;;;OAMG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAKjD;;;;;;;;OAQG;IACG,SAAS,CACb,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,4BAA4B,CAAC,OAAO,CAAC,CAAC;QAC9C,KAAK,CAAC,EAAE,4BAA4B,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,CAAC,EAAE,4BAA4B,CAAC,QAAQ,CAAC,CAAC;KAC5C,GACL,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAKjD;;;;;;;;OAQG;IACG,cAAc,CAClB,IAAI,GAAE,6BAAkC,GACvC,OAAO,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAKnD;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAQlD;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAQ9C;;;;;;;OAOG;IACG,sBAAsB,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,8BAA8B,CAAC,wBAAwB,CAAC,CAAC;IAQpE;;;;;;OAMG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IAQpD;;;;;;OAMG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAOtD;;;;;OAKG;IACG,WAAW,CACf,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAIvD"}

package/dist/domains/users.js

@@ -0,0 +1,195 @@
+import { MeDocument, UpdateGamertagDocument, DeleteMyAccountDocument, UserDocument, UsersPaginatedDocument, UsersConnectionDocument, SetSuperAdminDocument, SetOperatorDocument, SetEarlyAccessOverrideDocument, UpdateUserTypeDocument, ForceLogoutUserDocument, UpdateUserStateDocument, FreePlayWindowDocument, } from '../generated/graphql.js';
+/**
+ * User identity & account management — exposed as `client.users`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`). After
+ * the database split the users table is management-owned, so game-api no longer
+ * exposes these identity mutations — calling them against a game-api endpoint
+ * throws {@link CrowdyGraphQLError} with `FORBIDDEN`, directing you to the
+ * management API. Only the read/identity surface a game client realistically
+ * needs lives here; super-admin / operator screens use the management UI
+ * directly rather than the SDK.
+ *
+ * Every method needs a valid session (a bearer token set by
+ * `client.auth.login()` / `register()` or `client.setToken()`); without one the
+ * server returns `UNAUTHENTICATED` — except {@link me}, which resolves to
+ * `null`. `BigInt` ids such as `userId` and `orgId` are decimal strings.
+ */
+export class UsersAPI {
+    constructor(graphql) {
+        this.graphql = graphql;
+    }
+    /**
+     * Validate the current bearer token and return the authenticated user record.
+     * Handy for restoring a session on SDK init.
+     *
+     * @returns The {@link User}, or `null` if the token is missing, expired, or
+     *   revoked (an invalid token resolves to `null` rather than throwing).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    async me() {
+        const data = await this.graphql.request(MeDocument);
+        return data.me;
+    }
+    /**
+     * Set the authenticated user's gamertag and disambiguation (and append a
+     * gamertag-history row). Only ever updates the caller. Requires a valid
+     * session.
+     *
+     * @param input - {@link UpdateGamertagInput}: the new `gamertag` (max 64
+     *   characters) and `disambiguation` (max 128 characters); the pair must be
+     *   unique across the platform.
+     * @returns The updated {@link User} (its `userId`, `gamertag`,
+     *   `disambiguation`, and `userType`).
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the gamertag +
+     *   disambiguation pair is already taken, `UNAUTHENTICATED` without a session,
+     *   or `FORBIDDEN` when called against game-api (call the management API).
+     */
+    async updateGamertag(input) {
+        const data = await this.graphql.request(UpdateGamertagDocument, { input });
+        return data.updateGamertag;
+    }
+    /**
+     * **Destructive, self-service** soft-delete of the caller's **own** account:
+     * anonymizes PII and revokes all sessions. Wallet, voxel, and donation history
+     * stay intact via foreign keys. Acts only on the caller (no target argument).
+     * Requires a valid session.
+     *
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a session, or
+     *   `FORBIDDEN` when called against game-api (call the management API).
+     */
+    async deleteMyAccount() {
+        const data = await this.graphql.request(DeleteMyAccountDocument);
+        return data.deleteMyAccount;
+    }
+    /**
+     * Report whether a free-play window is currently active and when the next one
+     * starts. **Public** — no session required.
+     *
+     * @returns The {@link FreePlayWindowInfo}.
+     */
+    async freePlayWindow() {
+        const data = await this.graphql.request(FreePlayWindowDocument);
+        return data.freePlayWindowInfo;
+    }
+    /**
+     * Look up any user by id. **Super-admin only** (regular callers can only read
+     * their own profile via {@link me}).
+     *
+     * @param id - Numeric user id (`BigInt` as a decimal string).
+     * @returns The {@link User}, or `null` if no such user.
+     */
+    async get(id) {
+        const data = await this.graphql.request(UserDocument, { id });
+        return data.user;
+    }
+    /**
+     * Search/list users with offset pagination. **Super-admin only.**
+     *
+     * @param opts - Optional `query` (prefix match over email/gamertag/id) and
+     *   `limit` / `offset`.
+     * @returns A page of users.
+     * @remarks Prefer {@link listConnection} (Relay cursor pagination) for large
+     *   result sets; the offset args here are deprecated server-side.
+     */
+    async paginated(opts = {}) {
+        const data = await this.graphql.request(UsersPaginatedDocument, opts);
+        return data.usersPaginated;
+    }
+    /**
+     * Relay-style cursor pagination over users — the preferred alternative to
+     * {@link paginated}. **Super-admin only.** Page with `first` plus the previous
+     * page's `pageInfo.endCursor` as `after`. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first`, `after`, and `query`.
+     * @returns A {@link UsersConnection}.
+     */
+    async listConnection(args = {}) {
+        const data = await this.graphql.request(UsersConnectionDocument, args);
+        return data.usersConnection;
+    }
+    /**
+     * Grant or revoke the platform `is_super_admin` flag on a user. **Super-admin
+     * only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant, `false` to revoke.
+     * @returns The updated user's `userId` + `isSuperAdmin`.
+     */
+    async setSuperAdmin(userId, value) {
+        const data = await this.graphql.request(SetSuperAdminDocument, {
+            userId,
+            value,
+        });
+        return data.setSuperAdmin;
+    }
+    /**
+     * Grant or revoke the platform `is_operator` flag (control-plane access) on a
+     * user. **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant, `false` to revoke.
+     * @returns The updated user's `userId` + `isOperator`.
+     */
+    async setOperator(userId, value) {
+        const data = await this.graphql.request(SetOperatorDocument, {
+            userId,
+            value,
+        });
+        return data.setOperator;
+    }
+    /**
+     * Force an early-access override on a user (bypasses the early-access gate).
+     * **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - `true` to grant the override, `false` to clear it.
+     * @returns The updated user's `userId` + `grantEarlyAccessOverride`.
+     */
+    async setEarlyAccessOverride(userId, value) {
+        const data = await this.graphql.request(SetEarlyAccessOverrideDocument, {
+            userId,
+            value,
+        });
+        return data.setEarlyAccessOverride;
+    }
+    /**
+     * Set a user's `user_type`. **Super-admin only.**
+     *
+     * @param userId - Target user id.
+     * @param value - The new user type string.
+     * @returns The updated user's `userId` + `userType`.
+     */
+    async updateType(userId, value) {
+        const data = await this.graphql.request(UpdateUserTypeDocument, {
+            userId,
+            value,
+        });
+        return data.updateUserType;
+    }
+    /**
+     * Revoke all of a user's sessions (force logout everywhere). **Super-admin
+     * only.**
+     *
+     * @param userId - Target user id.
+     * @returns `true` on success.
+     */
+    async forceLogout(userId) {
+        const data = await this.graphql.request(ForceLogoutUserDocument, {
+            userId,
+        });
+        return data.forceLogoutUser;
+    }
+    /**
+     * Replace a user's top-level state blob. **Super-admin only.**
+     *
+     * @param input - {@link UpdateUserStateInput} (`userId` + base64 `state`).
+     * @returns The updated user's `userId` + `state`.
+     */
+    async updateState(input) {
+        const data = await this.graphql.request(UpdateUserStateDocument, { input });
+        return data.updateUserState;
+    }
+}

package/dist/domains/voxels.d.ts

@@ -0,0 +1,136 @@
+import type { GraphQLClient } from '../client.js';
+import { type ListVoxelsQuery, type ListVoxelsQueryVariables, type ListVoxelUpdatesByDistanceQuery, type ListVoxelUpdatesByDistanceQueryVariables, type UpdateVoxelMutation, type UpdateVoxelMutationVariables, type VoxelUpdateHistoryQuery, type VoxelUpdateHistoryQueryVariables, type VoxelUpdateHistoryConnectionQuery, type VoxelUpdateHistoryConnectionQueryVariables, type RollbackVoxelUpdatesMutation, type RollbackVoxelUpdatesMutationVariables } from '../generated/graphql.js';
+/**
+ * Voxel-edit queries and mutations for an app's world on the **game-api**: list,
+ * distance scans, history, rollback, and single-voxel writes. Exposed as
+ * `client.voxels`.
+ *
+ * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
+ * app / chunk / local position that changed, the new voxel type, an optional
+ * base64 state blob, and who/when. A background maintenance job later folds these
+ * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
+ * this API for authoritative reads, audit history, and administrative rollback.
+ *
+ * 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.
+ * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
+ * - Voxel `state` blobs are **base64-encoded** binary.
+ *
+ * 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`). {@link VoxelsAPI.update} additionally
+ * requires the `update_voxel_data` runtime permission and
+ * {@link VoxelsAPI.rollback} the `manage_apps` permission
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
+ */
+export declare class VoxelsAPI {
+    private gql;
+    constructor(gql: GraphQLClient);
+    /**
+     * List recorded voxel edits for a single chunk, newest first (optionally only
+     * those at/after a timestamp). Read-only.
+     *
+     * @param input - {@link ListVoxelsInput}: `appId`, chunk `coordinates`, and an
+     *   optional inclusive `since` lower time bound (only edits with
+     *   `createdAt >= since`).
+     * @returns The matching {@link Voxel} edits, newest first (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    list(input: ListVoxelsQueryVariables['input']): Promise<ListVoxelsQuery['listVoxels']>;
+    /**
+     * List recorded voxel edits for all chunks within a cubic (Chebyshev) radius of
+     * a center chunk, grouped per chunk and ordered by increasing distance,
+     * paginated over chunks. Read-only.
+     *
+     * @param input - {@link ListVoxelUpdatesByDistanceInput}: `appId`,
+     *   `centerCoordinate`, `maxDistance` (in chunk units, integer `1-8`), optional
+     *   `limit` (max **chunks**, not voxels — default 1000) / `skip` (default 0),
+     *   and an optional `since` lower time bound.
+     * @returns A {@link VoxelUpdatesByDistanceResponse}: per-chunk groups of voxel
+     *   edits ordered by increasing distance from `centerCoordinate`, plus an echo
+     *   of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
+    listByDistance(input: ListVoxelUpdatesByDistanceQueryVariables['input']): Promise<ListVoxelUpdatesByDistanceQuery['listVoxelUpdatesByDistance']>;
+    /**
+     * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
+     * **Writes world state**; a background job later folds the edit into the
+     * chunk's packed grid. Requires voxel-edit permission for the target region:
+     * active app access plus the `update_voxel_data` runtime permission (and, where
+     * 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.
+     * @returns The resulting {@link Voxel}.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.
+     */
+    update(input: UpdateVoxelMutationVariables['input']): Promise<UpdateVoxelMutation['updateVoxel']>;
+    /**
+     * Read entries from the immutable voxel edit history (`voxel_updates_history`)
+     * for an app, newest first, optionally filtered by user id and a changed-at
+     * time window. Read-only.
+     *
+     * @param args - Query variables:
+     *   - `appId` — app whose history to read (`BigInt` decimal string).
+     *   - `userId` — optional filter: only edits made by this user (decimal string).
+     *   - `from` / `to` — optional inclusive changed-at time window (ISO-8601).
+     *   - `limit` — **deprecated** max entries (default 500, range `1-50000`).
+     *   - `offset` — **deprecated** entries to skip (default 0, range `0-1000000`).
+     * @returns The matching {@link VoxelUpdateHistoryEvent} entries, newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     * @remarks The `limit`/`offset` arguments use deprecated offset pagination.
+     *   For large histories prefer the Relay-style `voxelUpdateHistoryConnection(first:,
+     *   after:)` query (available on the schema via `client.graphql`) — page with
+     *   `first` plus the previous page's `after` cursor. See
+     *   https://docs.crowdedkingdoms.com/overview/pagination.
+     */
+    history(args: VoxelUpdateHistoryQueryVariables): Promise<VoxelUpdateHistoryQuery['voxelUpdateHistory']>;
+    /**
+     * Relay-style cursor pagination over the immutable voxel edit history — the
+     * preferred alternative to {@link history} for large histories. Page with
+     * `first` plus the previous page's `pageInfo.endCursor` as `after`; the
+     * `appId` is required and `userId`/`from`/`to` filters are optional. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - `appId` plus optional `userId`/`from`/`to` filters and
+     *   `first`/`after` cursor paging.
+     * @returns A {@link VoxelUpdateHistoryConnection} (`edges { cursor node }`,
+     *   `pageInfo`, `totalCount`).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    historyConnection(args: VoxelUpdateHistoryConnectionQueryVariables): Promise<VoxelUpdateHistoryConnectionQuery['voxelUpdateHistoryConnection']>;
+    /**
+     * Revert every voxel edit made by `userId` in `appId` between `from` and `to`,
+     * returning one result per affected voxel. **Defaults to a dry run**
+     * (`dryRun: true`) that only PREVIEWS the planned reversions without writing;
+     * pass `dryRun: false` to actually apply them (**destructive** — mutates world
+     * state). Privileged: requires the `manage_apps` permission on the org that
+     * owns `appId` (super admins bypass). Requires game-api ≥ v0.10.3.
+     *
+     * Pass `idempotencyKey` to make retries safe: replaying with the same key and
+     * identical input returns the first result instead of re-applying, while the
+     * same key with **different** input throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h. Unlike
+     * {@link ActorsAPI.delete}, the key is a **field on the input object**
+     * ({@link RollbackVoxelUpdatesInput}), not a separate argument.
+     *
+     * @param input - {@link RollbackVoxelUpdatesInput}: `appId`, `userId` (decimal
+     *   strings), the inclusive `from`/`to` window, `dryRun` (default `true`), and
+     *   an optional `idempotencyKey`.
+     * @returns One {@link RollbackVoxelEventResult} per affected voxel; each
+     *   `applied` flag is `true` only when actually written (always `false` in a
+     *   dry run).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `SCOPE_MISSING` /
+     *   `FORBIDDEN` (missing `manage_apps`), `BAD_USER_INPUT`, or
+     *   `UNAUTHENTICATED`.
+     */
+    rollback(input: RollbackVoxelUpdatesMutationVariables['input']): Promise<RollbackVoxelUpdatesMutation['rollbackVoxelUpdates']>;
+}
+//# sourceMappingURL=voxels.d.ts.map

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

@@ -0,0 +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"}

package/dist/domains/voxels.js

@@ -0,0 +1,153 @@
+import { ListVoxelsDocument, ListVoxelUpdatesByDistanceDocument, UpdateVoxelDocument, VoxelUpdateHistoryDocument, VoxelUpdateHistoryConnectionDocument, RollbackVoxelUpdatesDocument, } from '../generated/graphql.js';
+/**
+ * Voxel-edit queries and mutations for an app's world on the **game-api**: list,
+ * distance scans, history, rollback, and single-voxel writes. Exposed as
+ * `client.voxels`.
+ *
+ * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
+ * app / chunk / local position that changed, the new voxel type, an optional
+ * base64 state blob, and who/when. A background maintenance job later folds these
+ * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
+ * this API for authoritative reads, audit history, and administrative rollback.
+ *
+ * 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.
+ * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
+ * - Voxel `state` blobs are **base64-encoded** binary.
+ *
+ * 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`). {@link VoxelsAPI.update} additionally
+ * requires the `update_voxel_data` runtime permission and
+ * {@link VoxelsAPI.rollback} the `manage_apps` permission
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
+ */
+export class VoxelsAPI {
+    constructor(gql) {
+        this.gql = gql;
+    }
+    /**
+     * List recorded voxel edits for a single chunk, newest first (optionally only
+     * those at/after a timestamp). Read-only.
+     *
+     * @param input - {@link ListVoxelsInput}: `appId`, chunk `coordinates`, and an
+     *   optional inclusive `since` lower time bound (only edits with
+     *   `createdAt >= since`).
+     * @returns The matching {@link Voxel} edits, newest first (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    async list(input) {
+        const data = await this.gql.request(ListVoxelsDocument, { input });
+        return data.listVoxels;
+    }
+    /**
+     * List recorded voxel edits for all chunks within a cubic (Chebyshev) radius of
+     * a center chunk, grouped per chunk and ordered by increasing distance,
+     * paginated over chunks. Read-only.
+     *
+     * @param input - {@link ListVoxelUpdatesByDistanceInput}: `appId`,
+     *   `centerCoordinate`, `maxDistance` (in chunk units, integer `1-8`), optional
+     *   `limit` (max **chunks**, not voxels — default 1000) / `skip` (default 0),
+     *   and an optional `since` lower time bound.
+     * @returns A {@link VoxelUpdatesByDistanceResponse}: per-chunk groups of voxel
+     *   edits ordered by increasing distance from `centerCoordinate`, plus an echo
+     *   of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
+    async listByDistance(input) {
+        const data = await this.gql.request(ListVoxelUpdatesByDistanceDocument, { input });
+        return data.listVoxelUpdatesByDistance;
+    }
+    /**
+     * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
+     * **Writes world state**; a background job later folds the edit into the
+     * chunk's packed grid. Requires voxel-edit permission for the target region:
+     * active app access plus the `update_voxel_data` runtime permission (and, where
+     * 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.
+     * @returns The resulting {@link Voxel}.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.
+     */
+    async update(input) {
+        const data = await this.gql.request(UpdateVoxelDocument, { input });
+        return data.updateVoxel;
+    }
+    /**
+     * Read entries from the immutable voxel edit history (`voxel_updates_history`)
+     * for an app, newest first, optionally filtered by user id and a changed-at
+     * time window. Read-only.
+     *
+     * @param args - Query variables:
+     *   - `appId` — app whose history to read (`BigInt` decimal string).
+     *   - `userId` — optional filter: only edits made by this user (decimal string).
+     *   - `from` / `to` — optional inclusive changed-at time window (ISO-8601).
+     *   - `limit` — **deprecated** max entries (default 500, range `1-50000`).
+     *   - `offset` — **deprecated** entries to skip (default 0, range `0-1000000`).
+     * @returns The matching {@link VoxelUpdateHistoryEvent} entries, newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     * @remarks The `limit`/`offset` arguments use deprecated offset pagination.
+     *   For large histories prefer the Relay-style `voxelUpdateHistoryConnection(first:,
+     *   after:)` query (available on the schema via `client.graphql`) — page with
+     *   `first` plus the previous page's `after` cursor. See
+     *   https://docs.crowdedkingdoms.com/overview/pagination.
+     */
+    async history(args) {
+        const data = await this.gql.request(VoxelUpdateHistoryDocument, args);
+        return data.voxelUpdateHistory;
+    }
+    /**
+     * Relay-style cursor pagination over the immutable voxel edit history — the
+     * preferred alternative to {@link history} for large histories. Page with
+     * `first` plus the previous page's `pageInfo.endCursor` as `after`; the
+     * `appId` is required and `userId`/`from`/`to` filters are optional. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - `appId` plus optional `userId`/`from`/`to` filters and
+     *   `first`/`after` cursor paging.
+     * @returns A {@link VoxelUpdateHistoryConnection} (`edges { cursor node }`,
+     *   `pageInfo`, `totalCount`).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    async historyConnection(args) {
+        const data = await this.gql.request(VoxelUpdateHistoryConnectionDocument, args);
+        return data.voxelUpdateHistoryConnection;
+    }
+    /**
+     * Revert every voxel edit made by `userId` in `appId` between `from` and `to`,
+     * returning one result per affected voxel. **Defaults to a dry run**
+     * (`dryRun: true`) that only PREVIEWS the planned reversions without writing;
+     * pass `dryRun: false` to actually apply them (**destructive** — mutates world
+     * state). Privileged: requires the `manage_apps` permission on the org that
+     * owns `appId` (super admins bypass). Requires game-api ≥ v0.10.3.
+     *
+     * Pass `idempotencyKey` to make retries safe: replaying with the same key and
+     * identical input returns the first result instead of re-applying, while the
+     * same key with **different** input throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h. Unlike
+     * {@link ActorsAPI.delete}, the key is a **field on the input object**
+     * ({@link RollbackVoxelUpdatesInput}), not a separate argument.
+     *
+     * @param input - {@link RollbackVoxelUpdatesInput}: `appId`, `userId` (decimal
+     *   strings), the inclusive `from`/`to` window, `dryRun` (default `true`), and
+     *   an optional `idempotencyKey`.
+     * @returns One {@link RollbackVoxelEventResult} per affected voxel; each
+     *   `applied` flag is `true` only when actually written (always `false` in a
+     *   dry run).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `SCOPE_MISSING` /
+     *   `FORBIDDEN` (missing `manage_apps`), `BAD_USER_INPUT`, or
+     *   `UNAUTHENTICATED`.
+     */
+    async rollback(input) {
+        const data = await this.gql.request(RollbackVoxelUpdatesDocument, { input });
+        return data.rollbackVoxelUpdates;
+    }
+}