@crowdedkingdomstudios/crowdyjs 5.2.0 → 5.3.0

package/dist/domains/auth.js

@@ -1,23 +1,53 @@
+import { ChangePasswordDocument, ConfirmEmailDocument, LoginDocument, LogoutAllDevicesDocument, LogoutDocument, RegisterDocument, RequestPasswordResetDocument, ResendConfirmationEmailDocument, ResetPasswordDocument, } from '../generated/graphql.js';
 /**
- * Auth sub-client. Talks to `cks-management-api` (NOT the game API) because
- * the management API owns the `game_tokens` table that backs every login /
- * register / password / email-confirm flow.
+ * Authentication and account-lifecycle flows — exposed as `client.auth`.
+ *
+ * Targets the **management-api**: every call routes to `managementUrl` (falling
+ * back to the game-api endpoint only in legacy single-endpoint mode). The
+ * management API owns the `game_tokens` table that backs every login / register
+ * / password / email-confirmation flow; the `token` it returns is a
+ * `game_tokens` row that game-api validates against the same shared Postgres.
+ *
+ * {@link login} and {@link register} mint that session token **and** store it on
+ * the shared session state automatically, so every later call on *either*
+ * endpoint (auth, users, apps, actors, chunks, udp, ...) is authenticated
+ * without you threading the token through by hand. Use {@link setToken} to
+ * rehydrate a saved token and {@link getToken} to read the current one. `BigInt`
+ * ids on the returned user (e.g. `userId`, `orgId`) are decimal strings.
  *
- * The returned `token` is a `game_tokens` row that game-api will validate
- * against the same shared Postgres. Once the SDK has a token, the rest of
- * the sub-clients (chunks, voxels, actors, udp, ...) use it transparently
- * via the shared `AuthState`.
+ * **Public — no session required:** {@link login}, {@link register},
+ * {@link confirmEmail}, {@link requestPasswordReset}, {@link resetPassword}, and
+ * {@link resendConfirmationEmail}. **Require a valid session:** {@link logout},
+ * {@link logoutAllDevices}, and {@link changePassword}, which otherwise throw
+ * {@link CrowdyGraphQLError} with `UNAUTHENTICATED` when the bearer token is
+ * missing, expired, or revoked.
  */
-import { ChangePasswordDocument, ConfirmEmailDocument, LoginDocument, LogoutAllDevicesDocument, LogoutDocument, RegisterDocument, RequestPasswordResetDocument, ResendConfirmationEmailDocument, ResetPasswordDocument, } from '../generated/graphql.js';
 export class AuthAPI {
     constructor(graphql, session) {
         this.graphql = graphql;
         this.session = session;
     }
     /**
-     * Log in and persist the resulting `game_tokens` bearer token via the
-     * shared `AuthState`. All subsequent SDK calls (game-api or
-     * management-api) include it automatically.
+     * Authenticate with email + password and start a new session. **Public** — no
+     * existing session required.
+     *
+     * On success the returned `token` is minted **and** stored on the shared
+     * session state, so subsequent calls on any sub-client (management-api or
+     * game-api) carry it automatically — no need to call {@link setToken}.
+     *
+     * @param input - Credentials ({@link LoginUserInput}): `email` and `password`
+     *   (min 8 characters).
+     * @returns An {@link AuthResponse}: the opaque session `token` (sent as
+     *   `Authorization: Bearer <token>`), `gameTokenId` (the session row id, a
+     *   string), and the authenticated `user`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` on invalid credentials, or
+     *   `BAD_USER_INPUT` on malformed input.
+     * @example
+     * ```ts
+     * const { user } = await client.auth.login({ email, password });
+     * // the session token is now stored; later calls are authenticated for you
+     * await client.users.me();
+     * ```
      */
     async login(input) {
         const data = await this.graphql.request(LoginDocument, { input });
@@ -26,7 +56,21 @@ export class AuthAPI {
         }
         return data.login;
     }
-    /** Register a new user. Same token-persistence behaviour as `login`. */
+    /**
+     * Create a new (initially unconfirmed) account, send a confirmation email, and
+     * return a session for immediate login. **Public** — no existing session
+     * required. Same token-persistence behaviour as {@link login}: the new `token`
+     * is stored on the shared session state automatically.
+     *
+     * @param input - New-account details ({@link RegisterUserInput}): `email`
+     *   (where the confirmation email is sent), `password` (min 8 characters), and
+     *   an optional initial `gamertag` (min 3 characters; can also be set later via
+     *   `client.users.updateGamertag`).
+     * @returns An {@link AuthResponse} (session `token`, `gameTokenId`, and the new
+     *   `user`).
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the email already exists or
+     *   the input is invalid.
+     */
     async register(input) {
         const data = await this.graphql.request(RegisterDocument, { input });
         if (data.register?.token) {
@@ -35,41 +79,106 @@ export class AuthAPI {
         return data.register;
     }
     /**
-     * Single-device logout. Clears the in-memory token after a successful
-     * server-side revoke so other sub-clients don't keep using it.
+     * Single-device logout: revoke the `game_tokens` row that authenticated this
+     * request; other devices/tokens are unaffected. After a successful server-side
+     * revoke the in-memory token is cleared from the shared session state so the
+     * other sub-clients stop using it. Requires a valid session.
+     *
+     * @returns `true` if a token was revoked, or `false` if the request carried no
+     *   game token.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the session is invalid.
      */
     async logout() {
         const data = await this.graphql.request(LogoutDocument);
         this.session.setToken(null);
         return data.logout;
     }
-    /** Revoke every `game_tokens` row for the current user. */
+    /**
+     * Revoke **every** active session for the authenticated user (deletes all
+     * their `game_tokens` rows and records revocations). Requires a valid session;
+     * use {@link logout} to end only the current one.
+     *
+     * Note: unlike {@link logout}, this does not clear the SDK's in-memory token —
+     * call {@link setToken}`(null)` afterwards if you also want to drop it locally.
+     *
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the session is invalid.
+     */
     async logoutAllDevices() {
         const data = await this.graphql.request(LogoutAllDevicesDocument);
         return data.logoutAllDevices;
     }
+    /**
+     * Confirm a user's email address using the token from the confirmation email.
+     * **Public** — the token itself authorizes the call.
+     *
+     * @param token - The confirmation token from the emailed link.
+     * @returns `true` on success, or `false` if the token is invalid or expired.
+     * @throws {CrowdyGraphQLError} on transport/validation failures (invalid or
+     *   expired tokens resolve to `false` rather than throwing).
+     */
     async confirmEmail(token) {
         const data = await this.graphql.request(ConfirmEmailDocument, { token });
         return data.confirmEmail;
     }
+    /**
+     * Start the password-reset flow by emailing a reset link to the address.
+     * **Public**. Always returns `true` regardless of whether the email exists or
+     * is confirmed, to prevent account enumeration.
+     *
+     * @param email - Email address to send the password-reset link to.
+     * @returns `true` (always, even when no such account exists).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     async requestPasswordReset(email) {
         const data = await this.graphql.request(RequestPasswordResetDocument, {
             email,
         });
         return data.requestPasswordReset;
     }
+    /**
+     * Complete a password reset using the reset token and a new password.
+     * **Public** — the reset token authorizes the call. Existing sessions are
+     * **not** revoked.
+     *
+     * @param input - {@link ResetPasswordInput}: the `token` from the emailed reset
+     *   link and the `newPassword` to set (min 8 characters).
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the token is invalid or
+     *   expired.
+     */
     async resetPassword(input) {
         const data = await this.graphql.request(ResetPasswordDocument, {
             input,
         });
         return data.resetPassword;
     }
+    /**
+     * Re-send the email-confirmation link. **Public**. Always returns `true`
+     * regardless of whether the account exists or is already confirmed (prevents
+     * enumeration); the email is only actually sent for existing unconfirmed
+     * accounts.
+     *
+     * @param email - Email address of the account to re-send confirmation to.
+     * @returns `true` (always).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     async resendConfirmationEmail(email) {
         const data = await this.graphql.request(ResendConfirmationEmailDocument, {
             email,
         });
         return data.resendConfirmationEmail;
     }
+    /**
+     * Change the authenticated user's password after verifying the current one.
+     * Requires a valid session. Existing sessions are **not** revoked.
+     *
+     * @param currentPassword - The user's current password, for verification.
+     * @param newPassword - The new password to set (min 8 characters).
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid session, or
+     *   `BAD_USER_INPUT` if the current password is wrong.
+     */
     async changePassword(currentPassword, newPassword) {
         const data = await this.graphql.request(ChangePasswordDocument, {
             currentPassword,
@@ -77,11 +186,22 @@ export class AuthAPI {
         });
         return data.changePassword;
     }
-    /** Imperatively replace the in-memory bearer token (e.g. on rehydrate). */
+    /**
+     * Imperatively replace the in-memory bearer token on the shared session state
+     * (e.g. to rehydrate a token persisted to disk). Affects every sub-client.
+     * Local only — performs no network call. Pass `null` to clear it.
+     *
+     * @param token - The bearer token to use, or `null` to clear the session.
+     */
     setToken(token) {
         this.session.setToken(token);
     }
-    /** Read the current bearer token. */
+    /**
+     * Read the current in-memory bearer token from the shared session state. Local
+     * only — performs no network call.
+     *
+     * @returns The current bearer token, or `null` if none is set.
+     */
     getToken() {
         return this.session.getToken();
     }

package/dist/domains/channels.d.ts

@@ -1,34 +1,293 @@
 import type { GraphQLClient } from '../client.js';
 import { type MyChannelsQuery, type MyChannelsQueryVariables, type ChannelsQuery, type ChannelsQueryVariables, type ChannelQuery, type ChannelQueryVariables, type ChannelMembersQuery, type ChannelMembersQueryVariables, type ChannelRolesQuery, type ChannelRolesQueryVariables, type ChannelPolicyQuery, type ChannelPolicyQueryVariables, type SetChannelPolicyMutation, type SetChannelPolicyMutationVariables, type CreateChannelMutation, type CreateChannelMutationVariables, type UpdateChannelMutation, type UpdateChannelMutationVariables, type DeleteChannelMutationVariables, type JoinChannelMutation, type JoinChannelMutationVariables, type RequestToJoinChannelMutation, type RequestToJoinChannelMutationVariables, type LeaveChannelMutationVariables, type AddChannelMemberMutation, type AddChannelMemberMutationVariables, type RemoveChannelMemberMutationVariables, type SetChannelMemberRolesMutation, type SetChannelMemberRolesMutationVariables, type CreateChannelRoleMutation, type CreateChannelRoleMutationVariables, type UpdateChannelRoleMutation, type UpdateChannelRoleMutationVariables, type DeleteChannelRoleMutationVariables } 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 declare class ChannelsAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * 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.
+     */
     mine(appId: MyChannelsQueryVariables['appId']): Promise<MyChannelsQuery['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.
+     */
     list(appId: ChannelsQueryVariables['appId']): Promise<ChannelsQuery['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.
+     */
     get(groupId: ChannelQueryVariables['groupId']): Promise<ChannelQuery['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.
+     */
     members(groupId: ChannelMembersQueryVariables['groupId']): Promise<ChannelMembersQuery['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.
+     */
     roles(groupId: ChannelRolesQueryVariables['groupId']): Promise<ChannelRolesQuery['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.
+     */
     policy(appId: ChannelPolicyQueryVariables['appId']): Promise<ChannelPolicyQuery['channelPolicy']>;
+    /**
+     * 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`.
+     */
     create(input: CreateChannelMutationVariables['input']): Promise<CreateChannelMutation['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`.
+     */
     update(input: UpdateChannelMutationVariables['input']): Promise<UpdateChannelMutation['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`.
+     */
     remove(groupId: DeleteChannelMutationVariables['groupId']): Promise<boolean>;
+    /**
+     * 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`.
+     */
     setPolicy(input: SetChannelPolicyMutationVariables['input']): Promise<SetChannelPolicyMutation['setChannelPolicy']>;
+    /**
+     * 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`.
+     */
     join(groupId: JoinChannelMutationVariables['groupId']): Promise<JoinChannelMutation['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`.
+     */
     requestToJoin(groupId: RequestToJoinChannelMutationVariables['groupId']): Promise<RequestToJoinChannelMutation['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`.
+     */
     leave(groupId: LeaveChannelMutationVariables['groupId']): Promise<boolean>;
+    /**
+     * 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`.
+     */
     addMember(groupId: AddChannelMemberMutationVariables['groupId'], userId: AddChannelMemberMutationVariables['userId']): Promise<AddChannelMemberMutation['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`.
+     */
     removeMember(groupId: RemoveChannelMemberMutationVariables['groupId'], userId: RemoveChannelMemberMutationVariables['userId']): Promise<boolean>;
+    /**
+     * 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`.
+     */
     setMemberRoles(input: SetChannelMemberRolesMutationVariables['input']): Promise<SetChannelMemberRolesMutation['setChannelMemberRoles']>;
+    /**
+     * 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`.
+     */
     createRole(input: CreateChannelRoleMutationVariables['input']): Promise<CreateChannelRoleMutation['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`.
+     */
     updateRole(input: UpdateChannelRoleMutationVariables['input']): Promise<UpdateChannelRoleMutation['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`.
+     */
     deleteRole(groupRoleId: DeleteChannelRoleMutationVariables['groupRoleId']): Promise<boolean>;
 }
 //# sourceMappingURL=channels.d.ts.map

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

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