@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/commands.d.ts

@@ -0,0 +1,328 @@
+import type { Message, MessageCore } from "./messages.js";
+import type { CommandArgumentMetadata, CommandArgumentRejectionReason, CommandArgumentSchema } from "./command-arguments.js";
+/**
+ * Names, help text and positional arguments for a command such as `!repeat hello 3`.
+ * Each API's command type adds the callback that runs when this name or an alias matches.
+ * Registration copies this data, so later edits do not change an existing router.
+ * Individual and batch command registration read recognized fields once, including inherited and non-enumerable fields
+ *
+ * @category Commands
+ */
+export interface PrefixCommandDefinition {
+    /** Name without the prefix, such as `repeat`, beginning with an ASCII letter or digit and using only ASCII letters, digits, `_` or `-` */
+    readonly name: string;
+    /** Other names that run the same command, such as `r`. Names and aliases must not collide with a command or group in the same parent group */
+    readonly aliases?: readonly string[];
+    /** Text placed below the invocation in generated help. The router neither escapes markup nor sends the text */
+    readonly description?: string;
+    /** Help text after the command name, such as `<text> <count>`. Overrides argument-derived syntax, including when set to an empty string */
+    readonly usage?: string;
+    /** Named argument descriptors read in property order after the guard allows execution. Omit this to leave `args` unconverted and expose empty `values` */
+    readonly arguments?: CommandArgumentSchema;
+    /**
+     * Leave this command out of generated help and unknown-name suggestions, for example for owner-only tools. Defaults to false.
+     * A hidden command still runs when invoked by name or alias, so pair it with a guard to restrict who can use it
+     */
+    readonly hidden?: boolean;
+}
+/**
+ * Frozen command information for inspection and help generation.
+ * Contains no callbacks, cooldown store or resource candidates.
+ * Help visibility callbacks also receive group entries, identified by `kind: "group"`
+ *
+ * @category Commands
+ */
+export interface PrefixCommandMetadata extends Omit<PrefixCommandDefinition, "arguments"> {
+    /** Present for groups supplied to help visibility callbacks. Executable commands omit this property */
+    readonly kind?: "group";
+    /** Registered names from the outer group through this entry, such as `["admin", "inspect"]`. Root commands omit this property */
+    readonly path?: readonly string[];
+    /** Frozen argument descriptions used to generate usage text, without candidate objects */
+    readonly arguments?: readonly CommandArgumentMetadata[];
+}
+/**
+ * A named parent for commands, such as `admin` in `!admin inspect`.
+ * Register the group before adding children to its canonical path.
+ * Groups organize lookup and help only, with no handler, argument conversion, guard or cooldown.
+ * Each protected command needs its own guard
+ *
+ * @category Commands
+ */
+export interface PrefixCommandGroupDefinition {
+    /** Group name using command-name syntax. It must not collide with sibling command or group names and aliases */
+    readonly name: string;
+    /** Alternative names for entering this group, matched with the router's `caseSensitive` setting */
+    readonly aliases?: readonly string[];
+    /** Description shown below this group's help entry, without markup escaping or automatic delivery */
+    readonly description?: string;
+    /**
+     * Leave this group and everything inside it out of generated help and unknown-name suggestions. Defaults to false.
+     * Help treats a hidden group like a missing one. Its commands still run when invoked by name, so guard each one that needs it
+     */
+    readonly hidden?: boolean;
+}
+/**
+ * Frozen group information copied at registration, including its registered-name path for adding children or selecting help
+ *
+ * @category Commands
+ */
+export interface PrefixCommandGroupMetadata extends PrefixCommandGroupDefinition {
+    /** Distinguishes this non-executable group from a command in help visibility callbacks */
+    readonly kind: "group";
+    /** Registered names from the outermost group to this one, such as `["admin", "users"]`, even if the message used aliases */
+    readonly path: readonly string[];
+}
+/**
+ * Choose the existing parent group for a new command or child group
+ *
+ * @category Commands
+ */
+export interface PrefixCommandRegistrationOptions {
+    /** Registered parent names, not aliases, such as `["admin", "users"]`. Omit or use `[]` for root. Missing parents are not created */
+    readonly group?: readonly string[];
+}
+/**
+ * Why a known command did not execute, passed as a frozen value to its optional `onReject` callback.
+ * Inspect `_tag` to distinguish a denied guard, cooldown or invalid arguments.
+ * The router replies only when `onReject: "reply"` is selected, and it schedules no retry.
+ * That reply is limited: An active cooldown key is answered once until its `retryAtMs`, and a guard denial once per user
+ * and command every 5 seconds. Argument rejections are always answered
+ *
+ * @category Commands
+ */
+export type PrefixCommandRejection = {
+    /** A guard returned false or `{ deny }`, so the handler did not run */
+    readonly _tag: "CommandGuardRejected";
+    /** The text a guard returned with `{ deny }`, suitable for a reply. Absent when a guard returned false */
+    readonly reason?: string;
+} | {
+    /** This command's cooldown key is still active */
+    readonly _tag: "CommandCooldownActive";
+    /** Unix epoch milliseconds when this key can claim again, not a wait duration */
+    readonly retryAtMs: number;
+} | {
+    /** Argument conversion rejected before a cooldown was claimed. This value does not include the rejected token */
+    readonly _tag: "CommandArgumentRejected";
+    /** Descriptor name that rejected, or `arguments` when extra positional tokens remained */
+    readonly argument: string;
+    /** Missing, invalid, ambiguous or extra input, without its private text */
+    readonly reason: CommandArgumentRejectionReason;
+    /** Absent because argument rejection has no retry time. Declared only to permit optional retry-time access in shared handling */
+    readonly retryAtMs?: never;
+};
+/**
+ * A prefix matched but no executable command was selected.
+ * Passed as a frozen value to the router's optional `onUnmatched` callback, without an automatic response.
+ * Ignored bot messages and messages without a matching prefix do not produce this callback
+ *
+ * @category Commands
+ */
+export type PrefixCommandUnmatched = {
+    /** The parser returned a valid name absent from this router's selected parent group or root */
+    readonly _tag: "CommandUnknownName";
+    /** Name exactly as returned by the parser, before case-insensitive lookup */
+    readonly name: string;
+    /**
+     * The closest registered command or group name in the same parent, within a small edit distance, such as `ping` for `pong`.
+     * Absent when no name is close enough
+     */
+    readonly suggestion?: string;
+    /** Registered parent group names where lookup missed. Absent at root and does not include the unknown name */
+    readonly path?: readonly string[];
+} | {
+    /** The parser returned undefined, for example for prefix-only input, or reported a syntax mistake with a `reason` */
+    readonly _tag: "CommandParserRejected";
+    /**
+     * The parser's explanation of the syntax mistake, suitable for a reply, such as the quoted parser's note about a quote that never closes.
+     * Absent when the parser returned undefined, which is also the result for ordinary chat that merely starts with the prefix
+     */
+    readonly reason?: string;
+    /** Registered parent group names already consumed before the parser declined. Absent at root */
+    readonly path?: readonly string[];
+} | {
+    /** A group matched with no following name. The leaf parser, guard, cooldown and handler did not run */
+    readonly _tag: "CommandMissingSubcommand";
+    /** Registered names through the group that needs a subcommand */
+    readonly path: readonly string[];
+};
+/**
+ * Prefix text selected for one message: One prefix, a list of accepted prefixes, or undefined to ignore the message
+ *
+ * @category Commands
+ */
+export type PrefixCommandPrefixValue = string | readonly string[] | undefined;
+/**
+ * Text that starts a command invocation, such as `!`, or a list of accepted prefixes.
+ * A resolver can choose prefixes from each message, for example from per-community settings, and may return a promise.
+ * Return undefined to ignore the message.
+ * Prefixes must be nonempty strings, and arrays must be nonempty and contain no holes.
+ * Matching is exact at the start of message content, with the longest matching prefix selected
+ *
+ * @category Commands
+ */
+export type PrefixCommandPrefix<M extends MessageCore = Message> = string | readonly string[] | ((message: M) => PrefixCommandPrefixValue | PromiseLike<PrefixCommandPrefixValue>);
+/**
+ * Frozen input given to a custom parser after prefix matching and any group lookup
+ *
+ * @category Commands
+ */
+export interface PrefixCommandParseInput<M extends MessageCore = Message> {
+    /** Incoming message with the attached client's selected fields. The router does not fetch omitted fields */
+    readonly message: M;
+    /** Matched prefix as written, such as `!!` when both `!` and `!!` match */
+    readonly prefix: string;
+    /** Text after the prefix at root, or after consumed group names and their separator whitespace. Remaining text is not rewritten */
+    readonly source: string;
+    /** Registered parent group names already selected. Absent at root. Returning another name cannot change this parent */
+    readonly path?: readonly string[];
+}
+/**
+ * Parser result copied and frozen by the router before command callbacks run
+ *
+ * @category Commands
+ */
+export interface PrefixCommandParse {
+    /** Command name or alias using command-name syntax in the selected parent. A returned group name does not enter that group */
+    readonly name: string;
+    /** Positional string tokens in input order, without array holes. A custom parser defines how these tokens are split */
+    readonly args: readonly string[];
+    /** Argument text retained for callbacks. The default parser removes whitespace between name and arguments but preserves the remaining text */
+    readonly rawArgs: string;
+}
+/**
+ * A parser result that reports a syntax mistake in text that was meant as a command, such as a quote that never closes.
+ * Return it instead of undefined so `onUnmatched` receives the explanation as `reason` of `CommandParserRejected`.
+ * The router sends nothing by itself, so the application decides whether to turn the reason into a reply.
+ * The router passes the reason on unchanged and logs it at Debug, so keep it fixed text that is safe to show in a channel and leaves the sender's input out.
+ * Return undefined instead when the text is probably not a command, such as ordinary chat that begins with the prefix
+ *
+ * @category Commands
+ */
+export interface PrefixCommandParseRejection {
+    /** Nonempty explanation, such as `A double quote was opened but never closed`. Any other value is reported as a parser failure */
+    readonly reason: string;
+}
+/**
+ * Split arguments while keeping quoted words together, such as `repeat "hello world" 3`.
+ * Single and double quotes delimit text, and a backslash escapes the next character inside or outside quotes.
+ * Quotes and escapes are removed from `args`, but `rawArgs` retains the text after command-name separator whitespace.
+ * Empty quotes produce an empty token, which a text argument descriptor rejects.
+ * Returns undefined for empty input or an invalid command name.
+ * For a quote that never closes or a trailing backslash, it returns a `PrefixCommandParseRejection` with a fixed `reason`, which `onUnmatched` receives.
+ * An apostrophe in plain text opens a quote too, so `say don't` is rejected unless it is escaped as `don\'t`.
+ * This synchronous helper does not inspect the message or change the router's whitespace-only default.
+ * Use the public `commands.parseQuoted` helper as the router's `parse` option to opt in
+ */
+export declare function parseQuotedPrefixCommand<M extends MessageCore = Message>(input: PrefixCommandParseInput<M>): PrefixCommandParse | PrefixCommandParseRejection | undefined;
+/**
+ * Configure how an attached router recognizes command messages, without connecting or subscribing during construction
+ *
+ * @category Commands
+ */
+export interface PrefixCommandsOptions<M extends MessageCore = Message> extends PrefixCommandParsing<M> {
+    /** Prefix text, accepted-prefix list or per-message resolver, which may return a promise. If several prefixes match, the longest wins */
+    readonly prefix: PrefixCommandPrefix<M>;
+}
+/**
+ * Parsing and cooldown settings shared by both API styles, apart from the prefix, which each API resolves in its own way
+ *
+ * @category Commands
+ */
+export interface PrefixCommandParsing<M extends MessageCore = Message> {
+    /**
+     * Also accept a mention of the bot, such as `@bot ping`, as a prefix. Defaults to false.
+     * Both mention forms, `<@id>` and `<@!id>`, are accepted.
+     * The bot's user ID comes from the user in the gateway's READY, so normally no request is needed.
+     * When READY did not supply a valid ID, the first message that starts with a mention triggers one users.fetchSelf
+     * read, which concurrent messages share. A failed read is logged at Warn in the commands category, and mentions are then treated
+     * as ordinary text without a new read for a backoff that starts at 5 seconds and doubles per consecutive failure up to
+     * 5 minutes, unless READY supplies the ID first
+     */
+    readonly mentionPrefix?: boolean;
+    /**
+     * Split the command name and arguments, optionally using `commands.parseQuoted` for quoted words.
+     * By default, leading whitespace is trimmed, the name must use command-name syntax and trimmed arguments are split on whitespace.
+     * The default preserves `rawArgs` after removing the command-name separator whitespace.
+     * Groups are consumed first using fixed whitespace separators, then this parser runs once on the remaining command text.
+     * A custom parser cannot enter another group by returning its name.
+     * Return undefined to decline parsing and call optional `onUnmatched` feedback.
+     * Return a `PrefixCommandParseRejection` instead to decline with a `reason` that `onUnmatched` receives, as `commands.parseQuoted` does for an unclosed quote.
+     * A group with no following name reports `CommandMissingSubcommand` without calling the parser.
+     * Throws and malformed results use the attached subscription's error reporting, with no automatic response or retry
+     */
+    readonly parse?: (input: PrefixCommandParseInput<M>) => PrefixCommandParse | PrefixCommandParseRejection | undefined;
+    /** Skip messages whose author has `isBot` set, before prefix resolution. Defaults to true */
+    readonly ignoreBots?: boolean;
+    /** Require matching letter case for command and group names and aliases. Defaults to false. This does not change prefix or argument matching */
+    readonly caseSensitive?: boolean;
+    /**
+     * Size the router's own memory cooldown store, used by commands whose cooldown supplies no `store`, such as
+     * `{ maxEntries: 50_000 }`. Defaults to 10,000 keys, shared by every router derived from the same create.
+     * A full store never denies a new key: It removes expired keys first, then the reservation that expires soonest,
+     * which lets that key run again early.
+     * The same limit bounds the rejections `onReject: "reply"` remembers so that it does not repeat itself.
+     * Invalid options throw ConfigurationError when the router is created
+     */
+    readonly cooldowns?: MemoryCooldownOptions;
+}
+/**
+ * Request to reserve a cooldown after successful guard and argument conversion, before command execution
+ *
+ * @category Commands
+ */
+export interface CommandCooldownRequest {
+    /** Nonempty key combining command identity with the configured key suffix. Use the complete string as the store key */
+    readonly key: string;
+    /** Whole milliseconds to reserve, from 1 through 2,147,483,647 */
+    readonly durationMs: number;
+}
+/**
+ * Outcome of reserving a cooldown, selected by `_tag`.
+ * Only `CooldownAcquired` permits execution.
+ * A denied claim may call `onReject`, but the router does not wait or retry.
+ * Retry times are millisecond timestamps since 1970-01-01 UTC, not wait durations
+ *
+ * @category Commands
+ */
+export type CommandCooldownClaim = {
+    /** The store reserved this key and permits this invocation to execute */
+    readonly _tag: "CooldownAcquired";
+    /** Unix epoch milliseconds when the reservation expires */
+    readonly retryAtMs: number;
+} | {
+    /** An existing reservation for this key has not expired */
+    readonly _tag: "CooldownActive";
+    /** Unix epoch milliseconds when this key can be claimed again */
+    readonly retryAtMs: number;
+};
+/**
+ * Whose invocations share one cooldown: The invoking user, the channel, or the guild.
+ * A guild cooldown in a direct message applies to that conversation
+ *
+ * @category Commands
+ */
+export type CommandCooldownPer = "user" | "channel" | "guild";
+/**
+ * A guard's decision: `true` allows the command, `false` denies it without an automatic reply, and `{ deny }` denies it
+ * with a reason that `onReject: "reply"` sends to the user.
+ * Both denials are counted and logged at Debug. A custom onReject callback receives either denial
+ *
+ * @category Commands
+ */
+export type PrefixCommandGuardResult = boolean | {
+    /** The reason the command was denied, sent to the user when rejection feedback is `"reply"` */
+    readonly deny: string;
+};
+/**
+ * Limit the cooldown keys held by one memory store in one process. Keys are not saved or shared with other processes
+ *
+ * @category Commands
+ */
+export interface MemoryCooldownOptions {
+    /**
+     * Positive safe integer key limit, defaulting to 10,000. A claim for a new key never fails for lack of space:
+     * A full store removes expired keys first, then the reservation that expires soonest, whose key can then claim again early
+     */
+    readonly maxEntries?: number;
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

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

package/dist/commands.js

@@ -0,0 +1,62 @@
+/**
+ * Split arguments while keeping quoted words together, such as `repeat "hello world" 3`.
+ * Single and double quotes delimit text, and a backslash escapes the next character inside or outside quotes.
+ * Quotes and escapes are removed from `args`, but `rawArgs` retains the text after command-name separator whitespace.
+ * Empty quotes produce an empty token, which a text argument descriptor rejects.
+ * Returns undefined for empty input or an invalid command name.
+ * For a quote that never closes or a trailing backslash, it returns a `PrefixCommandParseRejection` with a fixed `reason`, which `onUnmatched` receives.
+ * An apostrophe in plain text opens a quote too, so `say don't` is rejected unless it is escaped as `don\'t`.
+ * This synchronous helper does not inspect the message or change the router's whitespace-only default.
+ * Use the public `commands.parseQuoted` helper as the router's `parse` option to opt in
+ */
+export function parseQuotedPrefixCommand(input) {
+    const source = input.source.trimStart();
+    if (source.length === 0)
+        return undefined;
+    const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(source);
+    const name = match?.[1];
+    if (name === undefined || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name))
+        return undefined;
+    const rawArgs = match?.[2] ?? "";
+    const args = [];
+    let current = "";
+    let quote;
+    let started = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const character = rawArgs[index];
+        if (character === "\\") {
+            if (index + 1 === rawArgs.length)
+                return { reason: "A backslash at the end has nothing to escape" };
+            current += rawArgs[index + 1];
+            started = true;
+            index += 1;
+        }
+        else if (quote !== undefined) {
+            if (character === quote)
+                quote = undefined;
+            else
+                current += character;
+        }
+        else if (character === "'" || character === '"') {
+            quote = character;
+            started = true;
+        }
+        else if (/\s/.test(character)) {
+            if (started) {
+                args.push(current);
+                current = "";
+                started = false;
+            }
+        }
+        else {
+            current += character;
+            started = true;
+        }
+    }
+    if (quote !== undefined)
+        return { reason: `A ${quote === '"' ? "double" : "single"} quote was opened but never closed` };
+    if (started)
+        args.push(current);
+    return { name, rawArgs, args };
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAoOA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACpC,KAAiC;IAEjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAA;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACzC,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;IACvB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACrF,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAChC,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,IAAI,OAAO,GAAG,EAAE,CAAA;IAChB,IAAI,KAA4B,CAAA;IAChC,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAE,CAAA;QACjC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACrB,IAAI,KAAK,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM;gBAAE,OAAO,EAAE,MAAM,EAAE,8CAA8C,EAAE,CAAA;YACnG,OAAO,IAAI,OAAO,CAAC,KAAK,GAAG,CAAC,CAAE,CAAA;YAC9B,OAAO,GAAG,IAAI,CAAA;YACd,KAAK,IAAI,CAAC,CAAA;QACd,CAAC;aAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,SAAS,KAAK,KAAK;gBAAE,KAAK,GAAG,SAAS,CAAA;;gBACrC,OAAO,IAAI,SAAS,CAAA;QAC7B,CAAC;aAAM,IAAI,SAAS,KAAK,GAAG,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;YAChD,KAAK,GAAG,SAAS,CAAA;YACjB,OAAO,GAAG,IAAI,CAAA;QAClB,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,OAAO,EAAE,CAAC;gBACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBAClB,OAAO,GAAG,EAAE,CAAA;gBACZ,OAAO,GAAG,KAAK,CAAA;YACnB,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,OAAO,IAAI,SAAS,CAAA;YACpB,OAAO,GAAG,IAAI,CAAA;QAClB,CAAC;IACL,CAAC;IACD,IAAI,KAAK,KAAK,SAAS;QACnB,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,oCAAoC,EAAE,CAAA;IACnG,IAAI,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAClC,CAAC"}

package/dist/counts.d.ts

@@ -0,0 +1,124 @@
+import { FluxerlyError } from "./errors.js";
+import type { OperationOptions } from "./client.js";
+import type { ClientClosedError } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+/** The guild or channel count request named in an error.
+ * One call can send commands to several local shards but occupies one shared request slot and does not cache counts
+ *
+ * @category Errors
+ */
+export type CountOperation = "guilds.fetchCounts" | "channels.fetchMemberCounts";
+/**
+ * Member totals returned for one requested community by Fluxer's gateway.
+ * This frozen result is not cached and can become outdated immediately.
+ * Fluxer includes only visible members in onlineCount, so it does not count every online account
+ *
+ * @category Guilds and members
+ */
+export interface GuildCount {
+    /** Requested guild ID as a positive decimal string with no leading zeroes, no greater than 9223372036854775807 */
+    readonly guildId: string;
+    /** Member count Fluxer reported for this community, never negative */
+    readonly memberCount: number;
+    /** Visible online-member count Fluxer reported for this community, never negative */
+    readonly onlineCount: number;
+}
+/**
+ * Results from one explicit request for several community counts, ordered to match the requested IDs.
+ * The `omittedGuildIds` field lists requested IDs for which Fluxer returned no count.
+ * Do not treat an omission as zero or infer missing membership, denied access or a provider failure.
+ * A community assigned to an unowned or unready shard fails the call with notConnected instead
+ *
+ * @category Guilds and members
+ */
+export interface GuildCountsResult {
+    /** Frozen count entries in the caller's requested guild-ID order */
+    readonly counts: readonly GuildCount[];
+    /** Frozen requested guild IDs without a returned entry, in caller input order */
+    readonly omittedGuildIds: readonly string[];
+}
+/** Visible member totals for one requested channel, with the guild ID supplied by the gateway response.
+ * Counts concern this channel's visibility, not the full community membership
+ *
+ * @category Channels
+ */
+export interface ChannelMemberCount extends GuildCount {
+    /** Requested channel ID as a positive decimal string with no leading zeroes, no greater than 9223372036854775807 */
+    readonly channelId: string;
+    /** Nonnegative visible members Fluxer reported for this channel, not the community total */
+    readonly memberCount: number;
+    /** Nonnegative visible online members Fluxer reported for this channel, not the community total */
+    readonly onlineCount: number;
+}
+/**
+ * Results from one community's requested channel counts, ordered to match the requested channel IDs.
+ * The `omittedChannelIds` field lists requested IDs for which Fluxer returned no count. The SDK does not substitute zero or infer why.
+ * A community assigned to an unowned or unready shard fails the call with notConnected instead
+ *
+ * @category Channels
+ */
+export interface ChannelMemberCountsResult {
+    /** Frozen count entries in the caller's requested channel-ID order */
+    readonly counts: readonly ChannelMemberCount[];
+    /** Frozen requested channel IDs without a returned entry, in caller input order */
+    readonly omittedChannelIds: readonly string[];
+}
+/** Set how long one fresh gateway-count call can wait for its complete response.
+ * One deadline covers local registration, every routed shard command and all reply fragments.
+ * These calls require ready routed shards and do not fetch counts over REST as a fallback
+ *
+ * @category Options
+ */
+export interface CountOperationOptions {
+    /** Total reply deadline in milliseconds, integer 1–2,147,483,647, default 30,000.
+     * Includes local registration and gateway waiting
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Fresh-count settings for the default API, with the same deadline plus cancellation of this local wait only
+ *
+ * @category Options
+ */
+export interface DefaultCountOperationOptions extends CountOperationOptions, OperationOptions {
+}
+/**
+ * A fresh gateway-count call could not return its complete result.
+ * A failure releases this call's local wait and request slot and withdraws its unsent commands without retrying or caching partial counts.
+ * It does not cancel provider work already dispatched or establish whether that work continued.
+ * Error metadata includes no credential, requested IDs, correlation nonce or provider body
+ *
+ * @category Errors
+ */
+export declare class CountOperationError extends FluxerlyError {
+    /** Fixed name that identifies this error type */
+    readonly _tag = "CountOperationError";
+    /** SDK-owned local input detail, or null for non-input failures */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Requested count operation */
+    readonly operation: CountOperation;
+    /** Failure category.
+     * The reason input means local validation failed, and notConnected means a routed shard is absent or not ready.
+     * The reason busy means shared request capacity or a shard's internal command queue is full, and timeout means the reply deadline expired.
+     * The reason connectionLost means a participating shard lost its connection, and response means a matched reply was malformed
+     */
+    readonly reason: "input" | "notConnected" | "busy" | "timeout" | "connectionLost" | "response";
+    /** Describe a count failure. Construction sends no request and releases no request slot */
+    constructor(options: {
+        /** Requested count operation */
+        readonly operation: CountOperation;
+        /** Failure category, as described on the reason field */
+        readonly reason: CountOperationError["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;
+    });
+}
+/**
+ * Expected fresh-count failure. Native interruption and cancellation in the default API remain separate from this union
+ *
+ * @category Errors
+ */
+export type CountOperationFailure = CountOperationError | ClientClosedError;
+//# sourceMappingURL=counts.d.ts.map

package/dist/counts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"counts.d.ts","sourceRoot":"","sources":["../src/counts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,EAA+B,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE/F;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,4BAA4B,CAAA;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACvB,kHAAkH;IAClH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,iFAAiF;IACjF,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IAClD,oHAAoH;IACpH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC9C,mFAAmF;IACnF,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;CAChD;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA6B,SAAQ,qBAAqB,EAAE,gBAAgB;CAAG;AAEhG;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IAClD,iDAAiD;IACjD,QAAQ,CAAC,IAAI,yBAAwB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACtD,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,gBAAgB,GAAG,UAAU,CAAA;IAE9F,2FAA2F;IAC3F,YAAY,OAAO,EAAE;QACjB,gCAAgC;QAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;QAClC,yDAAyD;QACzD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAA;QAC9C,kLAAkL;QAClL,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAAA;QACnE,uDAAuD;QACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAC3B,EA2BA;CACJ;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,iBAAiB,CAAA"}

package/dist/counts.js

@@ -0,0 +1,52 @@
+import { FluxerlyError, operationDetails } from "./errors.js";
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js";
+import { freezeInputValidationDetail } from "./input-validation.js";
+/**
+ * A fresh gateway-count call could not return its complete result.
+ * A failure releases this call's local wait and request slot and withdraws its unsent commands without retrying or caching partial counts.
+ * It does not cancel provider work already dispatched or establish whether that work continued.
+ * Error metadata includes no credential, requested IDs, correlation nonce or provider body
+ *
+ * @category Errors
+ */
+export class CountOperationError extends FluxerlyError {
+    /** Fixed name that identifies this error type */
+    _tag = "CountOperationError";
+    /** SDK-owned local input detail, or null for non-input failures */
+    inputValidation;
+    /** Requested count operation */
+    operation;
+    /** Failure category.
+     * The reason input means local validation failed, and notConnected means a routed shard is absent or not ready.
+     * The reason busy means shared request capacity or a shard's internal command queue is full, and timeout means the reply deadline expired.
+     * The reason connectionLost means a participating shard lost its connection, and response means a matched reply was malformed
+     */
+    reason;
+    /** Describe a count failure. Construction sends no request and releases no request slot */
+    constructor(options) {
+        const { operation, reason, inputValidation = null } = options;
+        super(operationErrorMessage({
+            subject: "Count",
+            operation,
+            reason,
+            outcome: reason === "input" ? "notDispatched" : "unknown",
+            inputExplanation: inputValidation?.explanation ?? null,
+            facts: { read: true },
+        }), {
+            code: `count.${reason}`,
+            hint: operationFailureHint({
+                reason,
+                outcome: reason === "input" ? "notDispatched" : "unknown",
+                read: true,
+                inputPath: inputValidation?.path ?? null,
+            }),
+            cause: options.cause,
+            details: operationDetails({ operation, reason }),
+        });
+        this.name = this._tag;
+        this.inputValidation = freezeInputValidationDetail(inputValidation);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=counts.js.map

package/dist/counts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"counts.js","sourceRoot":"","sources":["../src/counts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAG7D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAE,2BAA2B,EAA8B,MAAM,uBAAuB,CAAA;AAwF/F;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAClD,iDAAiD;IACxC,IAAI,GAAG,qBAAqB,CAAA;IACrC,mEAAmE;IAC1D,eAAe,CAA8B;IACtD,gCAAgC;IACvB,SAAS,CAAgB;IAClC;;;;OAIG;IACM,MAAM,CAA+E;IAE9F,2FAA2F;IAC3F,YAAY,OASX;QACG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;QAC7D,KAAK,CACD,qBAAqB,CAAC;YAClB,OAAO,EAAE,OAAO;YAChB,SAAS;YACT,MAAM;YACN,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;YACzD,gBAAgB,EAAE,eAAe,EAAE,WAAW,IAAI,IAAI;YACtD,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;SACxB,CAAC,EACF;YACI,IAAI,EAAE,SAAS,MAAM,EAAE;YACvB,IAAI,EAAE,oBAAoB,CAAC;gBACvB,MAAM;gBACN,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;gBACzD,IAAI,EAAE,IAAI;gBACV,SAAS,EAAE,eAAe,EAAE,IAAI,IAAI,IAAI;aAC3C,CAAC;YACF,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,gBAAgB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;SACnD,CACJ,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,eAAe,GAAG,2BAA2B,CAAC,eAAe,CAAC,CAAA;QACnE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACxB,CAAC;CACJ"}