@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/pagination.ts

@@ -0,0 +1,172 @@
+import { FluxerlyError, operationDetails } from "./errors.js"
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+
+/** Read a Fluxer list one page at a time through an iterator or Effect Stream. Set item and page limits.
+ * Set maxItems to limit the number of delivered items. The SDK requests the next page only after the current one is consumed
+ *
+ * Each consumption of the iterator or Stream starts independently and copies the inputs then, not at creation
+ *
+ * Early exit, failure, interruption and client shutdown release that consumption's buffered page and tracking state.
+ * Already-delivered items remain with the caller
+ *
+ * The SDK does not fetch ahead, persist results or remove duplicates across separate consumptions
+ *
+ * Each page uses its own request deadline. The item and page caps do not provide a total elapsed-time deadline.
+ * Changes on Fluxer during traversal can cause the pages to differ from a single complete snapshot
+ *
+ * @category Options
+ */
+export interface PaginationQuery {
+    /** Maximum items to deliver, a required positive safe integer. Reaching this cap finishes normally, without proving remote exhaustion */
+    readonly maxItems: number
+    /** Maximum items to request per page, reduced when fewer items remain under maxItems.
+     * History defaults to 50 with a range of 1 through 100, members to 100 with 1 through 1,000.
+     * Community memberships default to 200 with 1 through 200, reaction users to 25 with 1 through 100.
+     * Pins default to 50 with 1 through 50, audit logs to 50 with 1 through 100.
+     * Member search defaults to 100 with 1 through 100, message search to 25 with 1 through 25
+     */
+    readonly pageSize?: number
+    /** Maximum page requests, a positive safe integer, default 100.
+     * Retrying a request for the same page does not use another page allowance. Duplicate-only pin pages do count.
+     * Needing a further page after this allowance fails with PaginationError reason pageLimit, preserving already-delivered items
+     */
+    readonly maxPages?: number
+}
+
+/** Limits and starting point for messages.iterateHistory, reading newest messages first.
+ * For newer-than or centered windows, use messages.fetchHistory with after or around instead
+ *
+ * @category Messages
+ */
+export interface HistoryIterationQuery extends PaginationQuery {
+    /** Start with messages older than this decimal message ID, excluding it. Omit to start with the latest visible messages */
+    readonly before?: string
+}
+
+/** Limits and starting point for ascending member or reaction-user traversal.
+ * Ordering follows user IDs, not join dates or reaction times
+ *
+ * @category Guilds and members
+ */
+export interface UserIterationQuery extends PaginationQuery {
+    /** Start with decimal user IDs greater than this ID, excluding it. Omit to start from the first page */
+    readonly after?: string
+}
+
+/**
+ * Limits and starting point for guilds.iterate, reading the bot's community memberships in ascending community-ID order
+ *
+ * @category Guilds and members
+ */
+export interface GuildIterationQuery extends PaginationQuery {
+    /** Start after this decimal community ID, excluding it. Omit for the first page.
+     * Repeated results caused by a removed cursor fail with PaginationError reason cursorStalled
+     */
+    readonly after?: string
+    /** Ask Fluxer to include approximate member and presence counts on each page, default false.
+     * Counts and permissions can still be omitted. An omitted summary field remains unavailable, not zero
+     */
+    readonly withCounts?: boolean
+}
+
+/** Limits and starting point for messages.iteratePins, reading newest pin times first.
+ * Each message ID is delivered at most once per consumption. Its first observed pin wins, even if it is later repinned.
+ * Timestamp ties or concurrent changes can prevent complete enumeration.
+ * If the next timestamp does not become older, traversal fails with cursorStalled after delivering newly observed IDs from that page
+ *
+ * @category Messages
+ */
+export interface PinIterationQuery extends PaginationQuery {
+    /** Start with older pin times than this ISO 8601 timestamp with a timezone. Omit to use Fluxer's current-time default */
+    readonly before?: string
+}
+
+/**
+ * Operation name included in a PaginationError or default-API SDK defect to identify the traversal
+ *
+ * @category Errors
+ */
+export type PaginationOperation =
+    | "iterateHistory"
+    | "messages.iterateSearch"
+    | "members.iterate"
+    | "guilds.iterate"
+    | "members.iterateSearch"
+    | "iterateReactionUsers"
+    | "iteratePins"
+    | "auditLogs.iterate"
+    | "threads.iterateMembers"
+
+/** What each non-input pagination failure means, for the error message */
+const paginationExplanations: Readonly<Record<PaginationError["reason"], string>> = {
+    input: "The iteration settings are invalid",
+    cursorStalled: "The next page did not move past the previous one, so iteration stopped to avoid repeating items",
+    pageLimit: "Reading another page would exceed maxPages",
+    indexing: "Fluxer is still building the search index, so iteration stopped without polling",
+}
+
+/** Suggested next step for each non-input pagination failure */
+const paginationHints: Readonly<Record<Exclude<PaginationError["reason"], "input">, string>> = {
+    cursorStalled: "Retry later, because concurrent changes or equal timestamps can repeat a cursor",
+    pageLimit: "Raise maxPages, or lower maxItems or raise pageSize so fewer pages are needed",
+    indexing: "Retry the search after a short wait",
+}
+
+/** Reading multiple pages failed because of invalid settings, a page limit, a stalled cursor or search readiness.
+ * Contains no resource IDs, response bodies or accumulated partial result.
+ * Items returned before the failure remain available to the application. A remote request failure keeps the underlying page-operation error instead of becoming PaginationError.
+ * Default-API cancellation uses CancelledError, while native interruption stays in Effect Cause. Unexpected defects remain separate
+ *
+ * @category Errors
+ */
+export class PaginationError extends FluxerlyError {
+    /** Literal error tag for identifying PaginationError */
+    readonly _tag = "PaginationError"
+    /** Frozen local validation detail for reason input, otherwise null */
+    readonly inputValidation: InputValidationDetail | null
+    /** Traversal that failed. Its presence does not establish that any page request was sent */
+    readonly operation: PaginationOperation
+    /** Failure category.
+     * The reason input means invalid settings, cursorStalled means no cursor progress, and pageLimit means another page would exceed maxPages.
+     * The reason indexing means message search is preparing an index and traversal will not poll it
+     */
+    readonly reason: "input" | "cursorStalled" | "pageLimit" | "indexing"
+    /** Identify the failed traversal and its local failure reason.
+     * Validation detail is copied and frozen when supplied, otherwise null. Construction does not start or resume traversal
+     */
+    constructor(options: {
+        /** Traversal that failed */
+        readonly operation: PaginationOperation
+        /** Failure category, as described on the reason field */
+        readonly reason: PaginationError["reason"]
+        /** Safe local validation detail copied into inputValidation. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        /** Underlying failure retained as the error's cause */
+        readonly cause?: unknown
+    }) {
+        const { operation, reason, inputValidation = null } = options
+        super(
+            operationErrorMessage({
+                subject: "Pagination",
+                operation,
+                reason,
+                outcome: "notDispatched",
+                inputExplanation: inputValidation?.explanation ?? paginationExplanations[reason],
+            }),
+            {
+                code: `pagination.${reason}`,
+                hint:
+                    reason === "input"
+                        ? operationFailureHint({ reason, outcome: "notDispatched", inputPath: inputValidation?.path })
+                        : paginationHints[reason],
+                cause: options.cause,
+                details: operationDetails({ operation, reason }),
+            },
+        )
+        this.name = this._tag
+        this.inputValidation = freezeInputValidationDetail(inputValidation)
+        this.operation = operation
+        this.reason = reason
+    }
+}

package/src/permissions.ts

@@ -0,0 +1,74 @@
+import type { GuildChannel } from "./channels.js"
+import type { Guild, GuildMember, GuildRole, MemberReference } from "./guilds.js"
+
+/**
+ * Calculate a member's community or channel permission bits from supplied guild, member, role and channel data
+ *
+ * The `roles` list must include the implicit everyone role whose ID equals `guild.id` and every role in `member.roleIds`.
+ * Supply `channel` with permissionOverwrites to include that channel's explicit permission overrides.
+ * Omit `channel` to calculate community-level bits.
+ * For a thread, supply the thread as `channel` and its parent channel, with its overwrites, as `parentChannel`
+ *
+ * The calculation first combines everyone and assigned-role grants.
+ * It then applies channel overrides for everyone, the member's roles together, and finally the member.
+ * Allows win over denies within each stage.
+ * Owners and members with Administrator receive all 64 bits, including unknown bits.
+ * A thread has no overwrites of its own, so Fluxer calculates in its parent channel and then grants SendMessages
+ * exactly when SendMessagesInThreads is granted there. The calculation does the same
+ *
+ * Duplicate, incomplete or cross-community resources fail with GuildOperationError reason input
+ *
+ * The calculated bits do not prove that Fluxer will allow an action.
+ * The calculation does not check visibility, timeouts, role hierarchy, multi-factor authentication (MFA) or age gates.
+ * In a thread it also does not check whether the member can see a private thread, which Fluxer allows only to its
+ * members and to members who can manage threads, or whether the thread is archived or locked.
+ * The result can become stale immediately after the input was observed
+ *
+ * @example
+ * ```ts
+ * import type { Client, PermissionInput, PermissionTarget } from "@neontechspace/fluxerly"
+ *
+ * export function permissionsExample(client: Client, input: PermissionInput, target: PermissionTarget) {
+ *     return {
+ *         local: client.permissions.calculate(input),
+ *         remote: client.permissions.fetch(target),
+ *     }
+ * }
+ * ```
+ *
+ * @category Roles and permissions
+ */
+export interface PermissionInput {
+    /** Community that owns the member, roles, and optional channel */
+    readonly guild: Guild
+    /** Membership whose raw permissions are calculated */
+    readonly member: GuildMember
+    /** Complete role observations needed to resolve everyone and every member role */
+    readonly roles: readonly GuildRole[]
+    /** Target channel's explicit overwrites, or a thread whose permissions come from `parentChannel`. Omit for a
+     * community-level calculation
+     */
+    readonly channel?: GuildChannel
+    /**
+     * Parent channel of a thread supplied as `channel`, with its permission overwrites. Required when `channel` is a
+     * thread, and rejected otherwise. It must be in the same community and have the ID that the thread's `parentId`
+     * names
+     */
+    readonly parentChannel?: GuildChannel
+}
+
+/**
+ * Choose whose permission bits permissions.fetch should calculate from fresh REST reads
+ *
+ * Supply `channelId` to include a separate target-channel read, or omit it for community-level bits.
+ * The client reads guild, member, roles and optional channel in that order under one total deadline, without consulting caches.
+ * When the channel is a thread, the client also reads its parent channel under the same deadline and calculates as
+ * Fluxer does for the thread.
+ * Resources can change between reads. The result is not one simultaneous snapshot and does not guarantee that Fluxer will allow an action
+ *
+ * @category Roles and permissions
+ */
+export interface PermissionTarget extends MemberReference {
+    /** Decimal community-channel ID for a channel-scoped calculation */
+    readonly channelId?: string
+}

package/src/pins.ts

@@ -0,0 +1,65 @@
+import type { Message, MessageCore } from "./messages.js"
+
+/** Choose one page of pins for messages.fetchPins.
+ * Pages are ordered by when messages were pinned, not when they were created. Use iteratePins for bounded multi-page traversal.
+ * Fields are captured once. Invalid timestamps, limits and unknown properties are rejected before the request
+ *
+ * @category Messages
+ */
+export interface MessagePinsQuery {
+    /** Maximum pins requested in this page, an integer from 1 through 50, default 50 */
+    readonly limit?: number
+    /** Pin-time cursor as an ISO 8601 timestamp with seconds and a Z or ±hh:mm offset, such as "2026-01-01T00:00:00Z".
+     * Any fraction length is accepted and the value is sent unchanged. Page ordering and cursor progress retain every fractional digit
+     * and compare timestamps by instant across timezone offsets. Select older pin times. Omit to use Fluxer's
+     * current-time default. Other forms and impossible calendar dates are rejected before dispatch
+     */
+    readonly before?: string
+}
+
+/** One pin observed by a request, pairing a message snapshot with the time it was pinned.
+ * Later unpins, repins and message edits do not update this frozen object
+ *
+ * @category Messages
+ */
+export interface MessagePin<M extends MessageCore = Message> {
+    /** Message as returned by this page, using the client's messageFields selection */
+    readonly message: M
+    /** Time Fluxer pinned the message, preserved as an ISO 8601 string with a timezone */
+    readonly pinnedAt: string
+}
+
+/** One frozen page of pins, ordered newest pin time first.
+ * Pins added or removed during traversal, or pins with the same timestamp, can cause a multi-page list to miss messages.
+ * A message can recur on later timestamp pages, even though IDs are unique within one page
+ *
+ * @category Messages
+ */
+export interface MessagePinsPage<M extends MessageCore = Message> {
+    /** Pins in Fluxer's received order, with no more entries than the requested limit */
+    readonly items: readonly MessagePin<M>[]
+    /** True when Fluxer reports more visible pins after this page */
+    readonly hasMore: boolean
+    /** Timestamp to pass as before, using the last pin time when hasMore is true, otherwise null.
+     * In a manual loop, deduplicate message IDs and stop if this cursor fails to move to an older time
+     */
+    readonly nextBefore: string | null
+}
+
+/** Notice that a channel's pins changed, without identifying the pinned or unpinned message.
+ * Fetch pins explicitly for the current list. This event does not fetch it automatically
+ *
+ * @category Events and collectors
+ */
+export interface ChannelPinsUpdate {
+    /** Affected channel ID as a decimal string */
+    readonly channelId: string
+    /** Community ID when Fluxer supplies it. Omission means no community context was supplied, not a confirmed private channel.
+     * No channel lookup or cache inference supplies this field
+     */
+    readonly guildId?: string
+    /** Last-pin time supplied by Fluxer as an ISO 8601 string, or null.
+     * This value can stay unchanged after an unpin, so it is not a unique change cursor
+     */
+    readonly lastPinTimestamp: string | null
+}

package/src/presence.ts

@@ -0,0 +1,124 @@
+import { FluxerlyError, operationDetails } from "./errors.js"
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+
+/** The bot's visible status while connected, with dnd meaning do not disturb.
+ * Use invisible to hide online status, not to disconnect the client.
+ * The status offline is excluded because Fluxer normalizes it to invisible on a connected session
+ *
+ * @category Client and lifecycle
+ */
+export type PresenceStatus = "online" | "idle" | "dnd" | "invisible"
+
+/**
+ * One custom-status emoji. The variants cannot be combined
+ *
+ * @category Client and lifecycle
+ */
+export type CustomStatusEmoji =
+    | {
+          /** Decimal ID of an existing custom emoji. Fluxer checks availability for the bot's account */
+          readonly id: string
+      }
+    | {
+          /** One Unicode emoji. Fluxer validates that it is a supported single emoji */
+          readonly name: string
+      }
+
+/** Text, emoji and optional expiration for the bot's custom status.
+ * Fluxer makes the final checks for emoji availability, Unicode emoji semantics and whether expiration is still in the future
+ *
+ * @category Client and lifecycle
+ */
+export interface CustomStatusInput {
+    /** Status text, from 1 through 128 UTF-16 code units */
+    readonly text?: string
+    /** An explicit custom-emoji ID or one Unicode emoji */
+    readonly emoji?: CustomStatusEmoji
+    /** Future ISO-8601 expiration time. Impossible calendar dates are rejected before retaining the update.
+     * Fluxer rejects an expiry that passes before it receives the update
+     */
+    readonly expiresAt?: string
+}
+
+/**
+ * Set the status this bot should publish on its gateway connections.
+ * Use `customStatus: null` to request clearing the custom status.
+ * Omission preserves this client's latest custom-status request, or leaves the provider value unchanged if there is no retained request.
+ * The client copies the latest accepted settings and retains at most one unsent update per local shard, replacing its payload with the latest intent.
+ * Status updates are at least four seconds apart, measured from each actual socket transmission, not queue admission.
+ * It publishes those settings on ready local shards and restores them after READY or RESUMED.
+ * A successful call means the client accepted the settings. It does not mean every shard published them at once or that another user can see them.
+ * Shutdown clears the saved settings and pending local timers
+ *
+ * @category Client and lifecycle
+ */
+export interface PresenceInput {
+    /** Visible status to publish on the bot's live gateway connections */
+    readonly status: PresenceStatus
+    /** New custom status, null to clear it, or omission to retain the latest custom-status request made by this client */
+    readonly customStatus?: CustomStatusInput | null
+}
+
+/** The SDK rejected a status update or member-presence selection before changing its saved settings.
+ * The reason input includes invalid values or a community assigned to a shard this client does not own.
+ * The reason limit means the member selection exceeds a local count or encoded-byte budget
+ *
+ * @category Errors
+ */
+export class PresenceError extends FluxerlyError {
+    /** Error tag for identifying PresenceError in a Result */
+    readonly _tag = "PresenceError"
+    /** SDK-owned local input detail, or null for local limits and non-input failures */
+    readonly inputValidation: InputValidationDetail | null
+    /** Whether local validation failed or the selected members exceeded a local budget */
+    readonly reason: "input" | "limit"
+
+    /** Describe a rejected presence change. Construction changes no saved presence settings */
+    constructor(options: {
+        /** Whether local validation failed or the selected members exceeded a local budget */
+        readonly reason: PresenceError["reason"]
+        /** Safe local input detail. It never retains rejected values, credentials, or Fluxer data, and names an unsupported key only when it looks like a field name. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        /** Underlying failure retained as the error's cause */
+        readonly cause?: unknown
+    }) {
+        const { reason, inputValidation = null } = options
+        super(
+            operationErrorMessage({
+                subject: "Presence",
+                operation: "update",
+                reason,
+                outcome: "notDispatched",
+                inputExplanation:
+                    inputValidation?.explanation ??
+                    (reason === "limit"
+                        ? "The member selection is too large. The limits are 1,000 members per community, 10,000 members across at most 100 communities, and 4,096 bytes per gateway request"
+                        : null),
+            }),
+            {
+                code: `presence.${reason}`,
+                hint:
+                    reason === "limit"
+                        ? "Select fewer members, or clear the selection of communities that no longer need member presences"
+                        : operationFailureHint({
+                              reason,
+                              outcome: "notDispatched",
+                              inputPath: inputValidation?.path ?? null,
+                          }),
+                cause: options.cause,
+                details: operationDetails({ reason }),
+            },
+        )
+        this.name = this._tag
+        this.inputValidation = freezeInputValidationDetail(inputValidation)
+        this.reason = reason
+    }
+}
+
+/**
+ * Expected presence-operation failure. Client closure remains distinct from local input rejection
+ *
+ * @category Errors
+ */
+export type PresenceFailure = PresenceError | import("./errors.js").ClientClosedError

package/src/reaction-pages.ts

@@ -0,0 +1,106 @@
+import type { OperationOptions } from "./client.js"
+import type { CollectorFailure } from "./collectors.js"
+import type { EmbedBuilder } from "./builders.js"
+import type { EmbedInput } from "./embeds.js"
+import type { ConfigurationError } from "./errors.js"
+import type { MessageOperationFailure, SendError } from "./message-errors.js"
+import type { Message, MessageCore } from "./messages.js"
+import type { MessageReaction } from "./reactions.js"
+
+/** One page shown by reaction pages, such as `"Page 1"` or `{ embeds: [embed] }`.
+ * A string is the page's text. An object supplies text, embeds or both, and must not be empty.
+ * Showing a page replaces the message's text and embeds, so text from one page never stays on an embed-only page.
+ * Files, stickers and mentions are not supported on pages, and mention notifications stay off.
+ * Fluxer validates each page when it is sent or shown, so an invalid later page fails only when someone turns to it
+ *
+ * @category Messages
+ */
+export type PageInput =
+    | string
+    | {
+          /** Page text, without trimming. Omit for an embed-only page */
+          readonly content?: string
+          /** Page embeds in display order, as plain objects or EmbedBuilder instances. Omit for a text-only page */
+          readonly embeds?: readonly (EmbedInput | EmbedBuilder)[]
+      }
+
+/** Who may turn pages: A list of account IDs, or a synchronous check that returns true to accept a click.
+ * The check receives the reaction addition, or the removal in the default toggle mode, after the arrow is matched.
+ * Return true for anyone, as in `users: () => true`. Reactions by the bot itself are never clicks.
+ * A throw or a non-boolean return ends the pages with CollectorError reason filter, and is reported to the
+ * client-level onError with kind filter, or logged at Error
+ *
+ * @category Messages
+ */
+export type PageTurners = readonly string[] | ((reaction: MessageReaction) => boolean)
+
+/** Choose who may turn reaction pages and how long they listen.
+ * The bot adds ◀ and ▶ reactions, and each click on one shows the previous or next page, wrapping around at the ends.
+ * By default, adding or removing an arrow counts as one click, so the bot needs only Add Reactions and Read Message
+ * History. Registration needs a connected gateway, like messages.collectReactions
+ *
+ * @category Messages
+ */
+export interface PaginateOptions {
+    /**
+     * Who may turn pages.
+     * Required by messages.paginate, while a command context defaults to the command's author
+     */
+    readonly users?: PageTurners
+    /** Stop after this many milliseconds without an accepted click. Integer 1 through 2,147,483,647, default 60,000 */
+    readonly idleMs?: number
+    /** Stop after this many milliseconds from registration, regardless of clicks. Integer 1 through 2,147,483,647, default 300,000 */
+    readonly timeoutMs?: number
+    /** Count only added arrows, and remove the clicker's arrow after each turn so the next click is another addition.
+     * The bot then needs Manage Messages. Default false, where adding and removing an arrow both turn the page
+     */
+    readonly removeClicks?: boolean
+}
+
+/** Reaction page settings for the Promise and Result API.
+ * Aborting the signal stops listening, removes the bot's arrows and returns CancelledError, leaving the current page shown.
+ * The Effect entry point uses interruption instead
+ *
+ * @category Messages
+ */
+export interface DefaultPaginateOptions extends PaginateOptions, OperationOptions {}
+
+/** Reaction page settings for messages.paginate, where no message identifies an asker, so users is required
+ *
+ * @category Messages
+ */
+export interface ChannelPaginateOptions extends PaginateOptions {
+    /** Who may turn pages, such as `[userId]`, or `() => true` for anyone */
+    readonly users: PageTurners
+}
+
+/** Settings for messages.paginate in the Promise and Result API, with the signal described on DefaultPaginateOptions
+ *
+ * @category Messages
+ */
+export interface DefaultChannelPaginateOptions extends ChannelPaginateOptions, OperationOptions {}
+
+/** How reaction pages ended after listening normally.
+ * Failures, cancellation and interruption are returned in the failure channel instead
+ *
+ * @category Messages
+ */
+export interface PaginateResult<M extends MessageCore = Message> {
+    /** Latest snapshot of the page message, as sent or as returned by the last page change */
+    readonly message: M
+    /** Position of the page shown at the end, with 0 identifying the first page */
+    readonly page: number
+    /** The reason idle means idleMs passed without a click, timeout means timeoutMs passed and singlePage means only one
+     * page was sent, without arrows or listening
+     */
+    readonly reason: "idle" | "timeout" | "singlePage"
+}
+
+/** Expected reaction page failures: Invalid pages or options, a failed send, a failed page change, arrow or click
+ * removal, an unavailable or lost gateway, an overflowing listener or a failing users check.
+ * After the first page is sent, the message stays at its current page and the bot still removes its own arrows.
+ * When that removal also fails, the earlier failure is returned. After an otherwise normal end, the removal failure is returned
+ *
+ * @category Errors
+ */
+export type PaginateFailure = ConfigurationError | SendError | MessageOperationFailure | CollectorFailure

package/src/reactions.ts

@@ -0,0 +1,126 @@
+import type { MessageReference } from "./messages.js"
+import type { GuildEmoji } from "./expressions.js"
+
+/** Choose one page of users who reacted with a particular emoji.
+ * Pass to messages.fetchReactionUsers. Use iterateReactionUsers to traverse bounded multiple pages.
+ * Fields are captured once. Unknown properties and invalid limits or IDs are rejected before the request
+ *
+ * @category Messages
+ */
+export interface ReactionUsersQuery {
+    /** Maximum users requested in this page, an integer from 1 through 100, default 25 */
+    readonly limit?: number
+    /** Return user IDs greater than this decimal ID, excluding the cursor user. Omit to start at the first page */
+    readonly after?: string
+}
+
+/** Account identity returned in a reaction-user page.
+ * This frozen snapshot has no account methods, community membership details or automatically refreshed data
+ *
+ * @category Messages
+ */
+export interface ReactionUser {
+    /** Account ID as a decimal string, not a JavaScript number */
+    readonly id: string
+    /** Username at the time Fluxer returned this page */
+    readonly username: string
+    /** True if Fluxer marked the account as a bot, otherwise false */
+    readonly isBot: boolean
+}
+
+/** One frozen page of users who reacted with the requested emoji.
+ * Users are ordered by ascending ID. Concurrent reaction changes can affect later pages.
+ * Several pages do not represent one fixed list of people who reacted
+ *
+ * @category Messages
+ */
+export interface ReactionUsersPage {
+    /** Users ordered by ascending decimal ID, with no more than the requested limit */
+    readonly items: readonly ReactionUser[]
+    /** True when Fluxer reported more users after this page */
+    readonly hasMore: boolean
+    /** Cursor to pass as after for the next request. The last returned user ID when hasMore is true, otherwise null */
+    readonly nextAfter: string | null
+}
+
+/** Emoji accepted by reaction operations and reaction collector selection.
+ * Pass literal Unicode such as `"👍"`, custom markup such as `"<:party:123>"` or `"<a:party:123>"`,
+ * a `{ name, id, animated? }` value, or a `GuildEmoji` returned by `client.emojis`.
+ * Values returned by `format.parseCustomEmoji`, `emojis.fetchMetadata` and reaction events can be reused directly
+ *
+ * Custom names use 1 through 32 ASCII letters, digits, underscores or hyphens. IDs are decimal strings.
+ * Markup must occupy the whole string. Shortcodes such as `:wave:` and URL-encoded text are rejected.
+ * Custom animation flags are optional and do not change the request identity or collector match
+ *
+ * Unicode input is limited to 128 UTF-16 code units and rejects spaces, control characters and reserved markup characters.
+ * Fluxer checks that the emoji is supported and that the bot may use it. The SDK does not fetch the emoji or decide whether the bot has permission to use it
+ *
+ * @category Messages
+ */
+export type ReactionEmojiInput = string | ReactionEmoji | GuildEmoji
+
+/** Emoji identity supplied in a reaction event.
+ * This frozen value records the name and any custom ID or animation flag supplied by Fluxer
+ *
+ * @category Messages
+ */
+export interface ReactionEmoji {
+    /** Literal Unicode emoji text, or the custom emoji name at event time */
+    readonly name: string
+    /** Custom emoji ID as a decimal string. Absent for Unicode emoji */
+    readonly id?: string
+    /** Whether a custom emoji is animated, when supplied. Absence means unknown and Unicode emoji omit this field */
+    readonly animated?: boolean
+}
+
+/** Message address carried by a reaction event, with optional community context.
+ * The `id` field is the message ID.
+ * Gateway reconnection can miss events. An event does not show current counts or everyone who reacted.
+ * Additional provider data, such as member details and session identifiers, is not retained
+ *
+ * @category Messages
+ */
+export interface ReactionTarget extends MessageReference {
+    /** Owning community ID when supplied. Absence alone does not establish private-channel scope */
+    readonly guildId?: string
+}
+
+/** One reaction addition or removal delivered by Fluxer.
+ * The `userId` field identifies the user whose reaction changed. Another account can perform the removal
+ *
+ * @category Events and collectors
+ */
+export interface MessageReaction extends ReactionTarget {
+    /** Account ID of the user whose reaction was added or removed */
+    readonly userId: string
+    /** Emoji whose reaction changed */
+    readonly emoji: ReactionEmoji
+}
+
+/** Notice that every reaction using one emoji was cleared from a message.
+ * The affected users are not listed
+ *
+ * @category Events and collectors
+ */
+export interface MessageReactionEmojiRemoval extends ReactionTarget {
+    /** Emoji whose reactions were cleared */
+    readonly emoji: ReactionEmoji
+}
+
+/** Reaction additions grouped by Fluxer into one messageReactionAddMany event.
+ * Entries retain received order. This does not also emit messageReactionAdd for each entry.
+ * Subscribe to both addition events when both forms are needed. Reaction collectors already accept both.
+ * A batch counts as one queued event, and its full received JSON counts toward the pending-byte budget.
+ * The SDK does not ask Fluxer to batch events or fill in changes Fluxer did not send
+ *
+ * @category Events and collectors
+ */
+export interface MessageReactionBatch extends ReactionTarget {
+    /** Frozen additions on the target message, in received order */
+    readonly reactions: readonly {
+        /** Account ID whose reaction was added */
+        readonly userId: string
+        /** Emoji used for this addition */
+        readonly emoji: ReactionEmoji
+    }[]
+}