@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/events.ts

@@ -0,0 +1,144 @@
+import type { ResultAsync } from "neverthrow"
+import type { OperationOptions } from "#sdk/client"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+import type { EventOverflowError, EventReadError } from "#sdk/message-errors"
+import type { Message, MessageCore } from "#sdk/messages"
+import type { EventInvocation, EventWaitOptions, HandlerOptions, EventMap, EventName } from "#sdk/events"
+import type { FailureReport } from "#sdk/failures"
+
+/**
+ * Control one event subscription returned by on or subscribe.
+ * Closing this subscription leaves the client and its other subscriptions running.
+ * Use `await using` to close the subscription and wait for its cleanup when the enclosing block ends
+ *
+ * @category Events and collectors
+ */
+export interface Subscription {
+    /** Identifier of this subscription, such as messageCreate#3, used in failure reports and log records */
+    readonly id: string
+    /**
+     * Stop new deliveries, drop queued events and stop running handlers, without waiting for the handler that called close.
+     * When queued events are dropped, one events.discarded Debug record reports how many, and
+     * diagnostics().counters.eventsDropped.closed counts them
+     *
+     * @remarks
+     * Returns immediately and signals running handlers to stop.
+     * JavaScript promises that ignore the signal cannot be forcibly stopped
+     */
+    close(): void
+    /**
+     * Wait until this subscription has closed and the SDK has released its queue and listeners.
+     * Normal closure succeeds with no value, and overflow fails with EventOverflowError, even for a later waiter.
+     * Cancelling this wait affects only the waiter, not the subscription or other waiters.
+     * Later waits see the same subscription outcome.
+     * Do not await this subscription's own closure from inside its handler
+     *
+     * @remarks
+     * This does not wait for arbitrary application promises.
+     * Unexpected cleanup failures reject with SdkDefect
+     */
+    waitForClose(
+        options?: OperationOptions,
+    ): ResultAsync<void, EventOverflowError | CancelledError | ConfigurationError>
+    /**
+     * Close this subscription and wait for its cleanup, as `await using` does at the end of a block.
+     * An overflow outcome is not rethrown here. Read it from waitForClose when it matters
+     */
+    [Symbol.asyncDispose](): Promise<void>
+}
+
+/**
+ * Read future events one at a time with next, then end the subscription with close.
+ * Each subscription receives the event type chosen in client.subscribe and keeps no previously delivered history.
+ * The default event type is messageCreate
+ *
+ * @category Events and collectors
+ */
+export interface EventSubscription<
+    K extends EventName = "messageCreate",
+    M extends MessageCore = Message,
+> extends Subscription {
+    /**
+     * Wait for the next event, returning Ok(payload), or Ok(null) after normal closure.
+     * Only one pending next call is allowed.
+     * Another call returns EventReadBusyError.
+     * Aborting options.signal cancels this read without closing the subscription.
+     * Overflow discards the queue and remains an Err.
+     * Unexpected SDK failures reject with SdkDefect
+     */
+    next(
+        options?: OperationOptions,
+    ): ResultAsync<EventMap<M>[K] | null, EventReadError | CancelledError | ConfigurationError>
+}
+
+/**
+ * Configure how client.on schedules handlers and reports their failures.
+ * The type parameter T is the event payload that a partition function receives
+ *
+ * @category Events and collectors
+ */
+export interface EventHandlerOptions<T = unknown> extends HandlerOptions<T> {
+    /**
+     * Receive this subscription's failures instead of the client-level onError: A handler that threw or rejected,
+     * with the original error and the IDs of the message being handled, or overflow that stopped the subscription.
+     * A failure only queues its report, so the hook never holds a handler slot.
+     * Reports are delivered one at a time in order, with up to 64 waiting while the hook is busy. Later ones are logged
+     * instead, with fields.reportOutcome "queueFull", and counted in diagnostics().counters.reportsDropped.
+     * A hook that throws or rejects is logged with the original failure and never retried.
+     * Reports already queued when the subscription closes are still delivered.
+     * Client shutdown does not wait for a pending hook promise. The report it was handling and any queued ones are logged
+     * at Error instead, with fields.reportOutcome "interrupted" for the report being handled and "subscriptionClosed" for
+     * queued or later reports
+     */
+    readonly onError?: (report: FailureReport) => unknown
+}
+
+/**
+ * Configure a single client.waitFor call with a filter, limits and optional AbortSignal.
+ * The signal cancels this event wait, not the client
+ *
+ * @category Events and collectors
+ */
+export interface DefaultEventWaitOptions<K extends EventName, M extends MessageCore = Message>
+    extends EventWaitOptions<K, M>, OperationOptions {}
+
+/**
+ * Event middleware for the default API, run around each client.on handler invocation that starts after registration.
+ * It receives the invocation, a next function that runs the rest of the chain and the handler, and the invocation's cancellation signal.
+ * The promise returned by next resolves when the rest of the chain has finished, whether or not it failed, and never rejects.
+ * Failures after next are reported by the SDK where they occur, so middleware can time or trace a handler but cannot hide its failure.
+ * A middleware fails when it throws, rejects, or returns or resolves an Err result, and that failure is reported like a handler failure
+ *
+ * @category Events and collectors
+ */
+export type EventMiddleware<M extends MessageCore = Message> = (
+    invocation: EventInvocation<M>,
+    next: () => Promise<void>,
+    signal: AbortSignal,
+) => unknown
+
+/**
+ * Remove event middleware registered with client.use.
+ * Use `using` to remove it when the enclosing block ends
+ *
+ * @category Events and collectors
+ */
+export interface MiddlewareRegistration {
+    /** Stop applying the middleware to invocations that start later. Invocations already running keep their chain. Repeated calls do nothing */
+    close(): void
+    /** Remove the middleware, as `using` does at the end of a block */
+    [Symbol.dispose](): void
+}
+
+/**
+ * Stop receiving connection-state updates from client.observeState.
+ * Use `using` to close the observer when the enclosing block ends
+ *
+ * @category Client and lifecycle
+ */
+export interface StateObserver {
+    /** Stop delivering states and drop a pending one. Listener code already running is not cancelled. Repeated calls do nothing */
+    close(): void
+    /** Close this observer, as `using` does at the end of a block */
+    [Symbol.dispose](): void
+}

package/src/api/default/gateway.ts

@@ -0,0 +1,67 @@
+import type { ResultAsync } from "neverthrow"
+import type { OperationOptions } from "#sdk/client"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+import type { GatewaySendFailure } from "#sdk/gateway"
+
+/**
+ * Send gateway commands that have no SDK method, on this client's ready shards.
+ * This is an advanced escape hatch: The SDK validates the frame locally but does not know the command's meaning,
+ * and Fluxer closes the connection, ending the client, for commands it rejects.
+ * Observe replies to these commands through the raw event, subscribing before sending
+ *
+ * @category Client and lifecycle
+ */
+export interface GatewayCommands {
+    /**
+     * Send one command frame { op, d } on a Connected local shard.
+     * The data is copied through JSON encoding when the operation starts, so later changes to it have no effect, and the
+     * encoded frame must be at most 4,096 UTF-8 bytes, Fluxer's message limit. Undefined data is invalid. Pass null instead.
+     * Data JSON cannot encode, such as a cycle or a BigInt, fails with reason input.
+     * Heartbeat, Identify, Resume and server-only opcodes fail with reason reserved.
+     * Commands share the shard's outbound pacing with presence and request commands: At most 500 paced commands per
+     * rolling 60 seconds per session, retained across Resume and reset for a fresh Identify, sent in call order.
+     * Heartbeats, Identify and Resume are never delayed. At most 500 gateway.send commands may wait per shard, and
+     * further submissions fail with reason busy until transmission or cancellation releases queue capacity.
+     * Completion means the frame was handed to the connection, not that Fluxer received or accepted it.
+     * A sent Request Guild Members command, opcode 8, counts toward the 12 member requests that members.iterateChunks
+     * allows this client in any 11 seconds, or the children of one supervisor together, but this method never refuses one
+     * for that limit.
+     * Fluxer answers an opcode it does not define, missing data or invalid command fields with close code 4001 or 4002.
+     * The SDK treats both as permanent, so the client ends. Data must match Fluxer's command schema exactly.
+     * Observe any reply through the raw event, which receives every dispatch the session accepts.
+     * A shard that loses its connection before sending fails a waiting command with reason notReady, and the SDK never
+     * replays it after reconnecting. Each sent command is logged at Debug with code gateway.commandSent
+     *
+     * @remarks
+     * Cancellation through options.signal withdraws a command that is still waiting for the pacing budget and returns
+     * CancelledError. Withdrawal immediately releases its local queue capacity.
+     * A command already handed to the connection cannot be withdrawn.
+     * A malformed signal returns ConfigurationError before anything is queued. A throw from the data's own getters or
+     * toJSON rejects with SdkDefect code application.defect and the thrown value as its cause.
+     * Other unexpected failures reject with SdkDefect
+     *
+     * @example
+     * ```ts
+     * import type { Client, RawDispatch } from "@neontechspace/fluxerly"
+     * // Commands with an SDK method, such as community counts through client.guilds.fetchCounts, use that method instead
+     * export function sendCustomCommand(
+     *     client: Client,
+     *     command: { op: number; data: unknown; replyType: string },
+     *     onReply: (reply: RawDispatch) => void,
+     * ) {
+     *     // Subscribe before sending so the raw reply cannot be missed
+     *     const replies = client.on("raw", (dispatch) => {
+     *         if (dispatch.t === command.replyType) onReply(dispatch)
+     *     })
+     *     // Close the returned subscription once the reply has arrived
+     *     return client.gateway.send(0, command.op, command.data).map(() => replies)
+     * }
+     * ```
+     */
+    send(
+        shardId: number,
+        op: number,
+        d: unknown,
+        options?: OperationOptions,
+    ): ResultAsync<void, GatewaySendFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/guards.ts

@@ -0,0 +1,173 @@
+import type { DefaultPrefixCommandContext, DefaultPrefixCommandGuard } from "#sdk/default-commands"
+import type { PermissionName } from "#sdk/helpers"
+import type { Message, MessageCore } from "#sdk/messages"
+import type { GuildRole } from "#sdk/guilds"
+import { isThreadChannel } from "#sdk/channels"
+import {
+    applicationOwners,
+    cachedPermissionChannel,
+    fetchedPermissionChannel,
+    guardDenials,
+    inGuild,
+    missingPermissions,
+    notPrivateChannel,
+    ownerIds as validOwnerIds,
+    permissionNames,
+} from "#sdk/internal/command-guards"
+import { orThrow } from "./results.js"
+
+/**
+ * Built-in command guards for the most common access rules. Pass one or a list as a command's `guard`.
+ * Each denial carries a short reason that `onReject: "reply"` sends to the user.
+ * Invalid guard settings throw ConfigurationError when the guard is created
+ *
+ * @example
+ * ```ts
+ * import { guards, runBot } from "@neontechspace/fluxerly"
+ *
+ * export function moderationBot(token: string | undefined) {
+ *     return runBot({
+ *         token,
+ *         commands: {
+ *             prefix: "!",
+ *             commands: {
+ *                 purge: {
+ *                     guard: [guards.guildOnly(), guards.requirePermissions(["ManageMessages"])],
+ *                     execute: ({ reply }) => reply("Purging"),
+ *                 },
+ *             },
+ *         },
+ *     })
+ * }
+ * ```
+ *
+ * @category Commands
+ */
+export interface DefaultGuards {
+    /**
+     * Allow the command only for a message that carries its community's guildId, and deny every other message without a
+     * request. Fluxer's gateway supplies the guildId with every community message, so a message without one is denied even
+     * when its channel belongs to a community
+     */
+    guildOnly<M extends MessageCore = Message>(): DefaultPrefixCommandGuard<M>
+    /**
+     * Allow the command only in a confirmed one-to-one or group conversation, and deny every other message.
+     * A message with a guildId is denied without a request. For a message without one, the guard checks the
+     * direct-message cache, then the channel cache, and otherwise reads the channel once with directMessages.fetch,
+     * which also fills an enabled direct-message cache. Enable `cache.directMessages` to avoid a read for each
+     * invocation in the same conversation.
+     * A private conversation allows the command. A cached community channel, or a read that Fluxer answers with anything
+     * other than a private conversation, denies it. Any other read failure, such as a network failure, timeout or
+     * rejection, leaves the channel unconfirmed and fails the command, which is reported with the command name
+     */
+    dmOnly<M extends MessageCore = Message>(): DefaultPrefixCommandGuard<M>
+    /**
+     * Allow the command only for the owner of the bot's application, as Fluxer reports it.
+     * The first invocation reads the owner's user ID with application.fetch, and the guard keeps it for the rest of the
+     * client's lifetime, so later invocations decide without a request and an ownership transfer applies to a new client.
+     * Invocations that start before the first read completes each read it.
+     * A failed read, such as a network failure, timeout or rejection, keeps nothing and fails the command, which is
+     * reported with the command name, and the next invocation reads again
+     */
+    ownerOnly<M extends MessageCore = Message>(): DefaultPrefixCommandGuard<M>
+    /**
+     * Allow the command only for the given decimal user IDs, such as the bot owner's.
+     * An undefined argument, such as an unset environment variable, throws ConfigurationError rather than falling back
+     * to the application owner
+     */
+    ownerOnly<M extends MessageCore = Message>(ownerIds: string | readonly string[]): DefaultPrefixCommandGuard<M>
+    /**
+     * Allow the command only when the invoking member has every named permission in the message's channel, and deny it in
+     * direct messages. The guard reads the community, member, roles and channel from enabled caches first and fetches only
+     * what is missing, at most once each per invocation, then applies permissions.calculate.
+     * A cached channel without its overwrite list is read again instead of being treated as having no overwrites.
+     * A channel read that Fluxer answers without an overwrite list has no channel overwrites, so the member's role
+     * permissions decide.
+     * In a thread, the guard also reads the thread's parent channel the same way, cache first, and decides as Fluxer
+     * does: From the parent channel's permissions, with SendMessages granted exactly when SendMessagesInThreads is.
+     * It does not check whether the member can see a private thread or whether the thread is archived or locked.
+     * A channel of a type this SDK version does not know can take its permissions from elsewhere, so a read of one
+     * without an overwrite list denies the command rather than guessing.
+     * A failed read fails the command, which is reported with the command name.
+     * The decision does not guarantee that Fluxer allows a later action
+     */
+    requirePermissions<M extends MessageCore = Message>(names: readonly PermissionName[]): DefaultPrefixCommandGuard<M>
+}
+
+/**
+ * Built-in command guards, namely guildOnly, dmOnly, ownerOnly and requirePermissions
+ *
+ * @category Commands
+ */
+export const guards: DefaultGuards = Object.freeze({
+    guildOnly:
+        <M extends MessageCore>(): DefaultPrefixCommandGuard<M> =>
+        ({ message }) =>
+            inGuild(message) || { deny: guardDenials.guildOnly },
+    dmOnly:
+        <M extends MessageCore>(): DefaultPrefixCommandGuard<M> =>
+        async ({ client, message, signal }) => {
+            const denied = { deny: guardDenials.dmOnly }
+            if (inGuild(message)) return denied
+            if (client.directMessages.get(message.channelId) !== undefined) return true
+            if (client.channels.get(message.channelId) !== undefined) return denied
+            const read = await client.directMessages.fetch(message.channelId, { signal })
+            if (read.isOk()) return true
+            // A non-private answer is the expected result in a community channel and becomes the reported denial
+            if (notPrivateChannel(read.error)) return denied
+            throw read.error
+        },
+    ownerOnly: <M extends MessageCore>(
+        ...ownerIds: [] | [string | readonly string[]]
+    ): DefaultPrefixCommandGuard<M> => {
+        const denied = { deny: guardDenials.ownerOnly }
+        if (ownerIds.length === 0)
+            return async ({ client, message, signal }) => {
+                let owner = applicationOwners.get(client)
+                if (owner === undefined) {
+                    owner = orThrow(await client.application.fetch({ signal })).ownerId
+                    applicationOwners.set(client, owner)
+                }
+                return owner === message.author.id || denied
+            }
+        const owners = validOwnerIds(ownerIds[0])
+        return ({ message }) => owners.has(message.author.id) || denied
+    },
+    requirePermissions: <M extends MessageCore>(names: readonly PermissionName[]): DefaultPrefixCommandGuard<M> => {
+        const required = permissionNames(names)
+        return async (context) => {
+            if (!inGuild(context.message)) return { deny: guardDenials.guildOnly }
+            const bits = await memberPermissions(context)
+            if (bits === undefined) return { deny: guardDenials.unconfirmedChannel }
+            const missing = missingPermissions(bits, required)
+            return missing.length === 0 || { deny: guardDenials.missing(missing) }
+        }
+    },
+})
+
+/**
+ * Calculate the invoking member's channel permissions, reading each resource from the cache before fetching it.
+ * Undefined means the channel's permissions cannot be confirmed
+ */
+async function memberPermissions<M extends MessageCore>(
+    context: DefaultPrefixCommandContext<M>,
+): Promise<bigint | undefined> {
+    const { client, message, signal } = context
+    const guildId = message.guildId!
+    const target = { guildId, userId: message.author.id }
+    const options = { signal }
+    const guild = client.guilds.get(guildId) ?? orThrow(await client.guilds.fetch(guildId, options))
+    const member = client.members.get(target) ?? orThrow(await client.members.fetch(target, options))
+    const cached = [guildId, ...member.roleIds].map((id) => client.roles.get({ guildId, id }))
+    const roles = cached.every((role): role is GuildRole => role !== undefined)
+        ? cached
+        : orThrow(await client.roles.fetchAll(guildId, options))
+    const readChannel = async (channelId: string) =>
+        cachedPermissionChannel(client.channels.get(channelId)) ??
+        fetchedPermissionChannel(orThrow(await client.channels.fetch(channelId, options)))
+    const channel = await readChannel(message.channelId)
+    if (!isThreadChannel(channel)) return channel && client.permissions.calculate({ guild, member, roles, channel })
+    // A thread takes its permissions from its parent channel
+    const parentChannel = await readChannel(channel.parentId)
+    return parentChannel && client.permissions.calculate({ guild, member, roles, channel, parentChannel })
+}

package/src/api/default/guilds.ts

@@ -0,0 +1,271 @@
+import type { CountOperationFailure, DefaultCountOperationOptions, GuildCountsResult } from "#sdk/counts"
+import type {
+    GuildListQuery,
+    GuildListSummary,
+    GuildEdit,
+    GuildVanityUrl,
+    GuildVanityUrlUsage,
+    Guild,
+    GuildOperationFailure,
+    DefaultGuildOperationOptions,
+    DefaultModerationOptions,
+} from "#sdk/guilds"
+import type { GuildIterationQuery, PaginationError } from "#sdk/pagination"
+import type { DefaultOwnMessageDeletionOptions } from "#sdk/messages"
+import type { ResultAsync, Result } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Read community settings and bot memberships, or use the optional guild cache.
+ * Most operations use HTTP and do not need a gateway connection.
+ * The fetchCounts method differs because it requires a ready gateway, as described on that method
+ *
+ * @remarks
+ * Requests share the client's REST or upload slots across all assigned shards, four per local shard by default, up to 64 (rest.concurrency).
+ * Attachment-download slots are separate, four by default (rest.mediaConcurrency).
+ * Both pools together allow 256 waiting requests or 4 MiB of queued JSON by default (rest.maxQueued and rest.queuedJsonMaxBytes)
+ *
+ * The timeoutMs option defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured, for the whole request, including waits.
+ * Reads retry transport failures and HTTP 500, 502, 503 or 504 at most twice.
+ * Delays are 125–250 ms, then 250–500 ms, or a longer Retry-After.
+ * Confirmed HTTP 429 waits are separate and never reset the deadline.
+ * Input, not-found, permission and malformed-success failures are not retried
+ *
+ * Successful JSON is limited to 16 MiB before parsing, not total memory.
+ * A write's malformed or lost response can leave the write applied, without rollback
+ *
+ * Expected failures return GuildOperationError or ClientClosedError.
+ * Abort returns CancelledError after cleanup.
+ * Unexpected SDK or cleanup failures reject with SdkDefect
+ *
+ * @category Guilds and members
+ */
+export interface Guilds {
+    /**
+     * Request fresh, visibility-filtered counts for 1–100 communities over the connected gateway.
+     * Use distinct positive decimal IDs without leading zeros, no greater than "9223372036854775807".
+     * The IDs are copied when execution starts.
+     * Every community must belong to a ready shard assigned to this client.
+     * An unassigned or unready shard fails with notConnected, not an omitted result.
+     * The result contains frozen counts and omittedGuildIds in requested order.
+     * An omitted entry is unavailable, not zero, and does not explain why it is missing.
+     * Community counts are separate observations, not one consistent snapshot.
+     * A missing whole reply fails with timeout
+     *
+     * One call uses one of four client-wide gateway request slots until all shard commands and replies finish.
+     * The channels.fetchMemberCounts and members.iterateChunks methods share those slots.
+     * There is no waiting queue for request slots, so excess calls fail with busy.
+     * Commands may wait for gateway pacing, and a full internal command queue also fails with busy.
+     * The default 30,000 ms deadline includes registration, commands and all reply fragments.
+     * Cancellation or deadline expiry withdraws unsent commands and immediately releases local request capacity.
+     * Fluxer also limits member and presence work, so a local slot does not guarantee a reply.
+     * Only a gateway gap on a participating shard fails with connectionLost, and late replies are ignored.
+     * No REST fallback, connection, caching, polling or retries are performed.
+     * Expected failures use CountOperationError or ClientClosedError
+     *
+     * @remarks
+     * Abort returns CancelledError after local cleanup but cannot cancel Fluxer's dispatched work.
+     * Unexpected failures reject with SdkDefect
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export async function countsExample(client: Client, guildId: string, channelId: string) {
+     *     const guilds = await client.guilds.fetchCounts([guildId])
+     *     const channels = await client.channels.fetchMemberCounts(guildId, [channelId])
+     *     return { guilds, channels }
+     * }
+     * ```
+     */
+    fetchCounts(
+        guildIds: readonly string[],
+        options?: DefaultCountOperationOptions,
+    ): ResultAsync<GuildCountsResult, CountOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch one page of communities this bot belongs to, ordered by ascending guild ID.
+     * The limit option defaults to 200 and accepts 1–200.
+     * Choose either before or after, not both.
+     * Those cursors refer to existing memberships, and if a cursor community was removed, Fluxer may restart the page.
+     * The withCounts option defaults to false.
+     * Permission bits or requested approximate counts may be omitted, and an omitted value means unavailable, not zero.
+     * The frozen summaries do not read or populate the guild cache.
+     * No gateway connection or further page traversal is performed.
+     * Shared guild deadlines, retries and failures apply.
+     * This page is not a complete membership inventory or proof of matching gateway state
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export async function guildListExample(client: Client) {
+     *     const page = await client.guilds.fetchPage({ withCounts: true })
+     *     if (page.isErr()) return page
+     *     return page.value.map(({ id, permissions, approximateMemberCount }) => ({ id, permissions, approximateMemberCount }))
+     * }
+     * ```
+     */
+    fetchPage(
+        query?: GuildListQuery,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly GuildListSummary[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Read the bot's community memberships in ascending ID order, retaining one page and never prefetching.
+     * The maxItems option is required.
+     * The pageSize option defaults to 200, maxPages defaults to 100, and timeoutMs applies to each page.
+     * Iteration ends at maxItems or an empty page, not a short page.
+     * A repeated or backward ID after a removed cursor fails with PaginationError cursorStalled before delivering that page.
+     * Other traversal failures are input and pageLimit, and remote failures keep fetchPage's error.
+     * Each consumption copies inputs independently.
+     * Client closure releases the page and fails the next pull.
+     * The withCounts option applies to every page, but missing permission bits or counts remain unavailable, not zero.
+     * No gateway connection or cache fill is needed.
+     * Already delivered communities remain with the caller, and separate pages do not guarantee a consistent inventory
+     *
+     * @remarks
+     * Consume the iterable with a for await loop, which starts the first request.
+     * An expected failure yields one Err and ends iteration.
+     * Breaking the loop releases the buffered page.
+     * Abort interrupts pending request work and waits for cleanup
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function guildMembershipsExample(client: Client) {
+     *     return client.guilds.iterate({ maxItems: 1000 })
+     * }
+     * ```
+     */
+    iterate(
+        query: GuildIterationQuery,
+        options?: DefaultGuildOperationOptions,
+    ): AsyncIterable<
+        Result<GuildListSummary, GuildOperationFailure | PaginationError | CancelledError | ConfigurationError>
+    >
+    /**
+     * Remove this bot from one community while preserving its authored messages.
+     * HTTP 204 completes the removal, without waiting for a gateway event.
+     * The client remains usable for other communities
+     *
+     * Fluxer rejects owners or restricted memberships.
+     * Only confirmed HTTP 429 rejection retries.
+     * A lost response or cancellation can leave membership removed.
+     * Check fetch or the membership list to resolve an unknown outcome.
+     * Rejoining needs separate authorization
+     *
+     * Successful writes and writes with unknown outcomes invalidate cached guild resources and conflicting pending reads.
+     * A confirmed leave also forgets this client's selected member presences, while an unknown outcome keeps that selection.
+     * Any dispatched attempt clears channel and message caches, because messages need not identify their community.
+     * Objects already returned to the caller stay unchanged.
+     * This neither deletes the community nor shuts down the client
+     */
+    leave(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Irreversibly delete this bot's entire authored message history across one community.
+     * Use a decimal guild ID.
+     * Other authors' messages are preserved, and the bot stays in the community with the same roles
+     *
+     * Success follows Fluxer's empty HTTP 202 response, not a completed-job report, deletion count or gateway event.
+     * The community may still contain new or concurrent messages.
+     * Deletion can be partial and is not atomic.
+     * There is no recovery token or automatic reconciliation
+     *
+     * Bot credentials satisfy Fluxer's extra authentication checks, called sudo checks.
+     * No extra sudo fields or audit reason are accepted.
+     * Fluxer handles attachment removal without guaranteeing physical provider-storage or CDN erasure.
+     * The default deadline, rest.defaultTimeoutMs (30,000 ms unless configured), includes capacity and rate-limit waits.
+     * Only confirmed HTTP 429 rejection retries, and a 5xx or lost response never causes a replay.
+     * After dispatch, the entire enabled message cache is cleared and older pending reads cannot restore it.
+     * No gateway events are created locally.
+     * Cancellation or closure waits for request cleanup but cannot undo deletion.
+     * Options must include confirm: true. Without it, the call fails before any request with reason input and path options.confirm.
+     * Input, capacity and HTTP failures use GuildOperationError for guilds.deleteOwnMessages
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function deleteOwnMessagesExample(client: Client, channelId: string) {
+     *     return client.messages.deleteOwnMessages(channelId, { confirm: true })
+     * }
+     * export function deleteOwnGuildMessagesExample(client: Client, guildId: string) {
+     *     return client.guilds.deleteOwnMessages(guildId, { confirm: true })
+     * }
+     * ```
+     */
+    deleteOwnMessages(
+        guildId: string,
+        options: DefaultOwnMessageDeletionOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch a community's custom invite code, URL and use count with ManageGuild permission.
+     * A null code and URL means the community has no custom invite.
+     * The read is remote, without a vanity cache or gateway connection.
+     * Shared guild read retries, deadline, cancellation and failure rules apply
+     */
+    fetchVanityUrl(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<GuildVanityUrlUsage, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Set a community's custom invite code, replace it, or pass null to remove it.
+     * The code must already be lowercase, 2–32 ASCII letters or digits with single internal hyphens.
+     * No automatic normalization is performed
+     *
+     * ManageGuild is required.
+     * Setting a code also requires the community's VANITY_URL feature.
+     * Reserved or taken codes fail remotely.
+     * Changing a code releases the old code and starts a new use count, and reclaiming the old code is not guaranteed.
+     * Success returns the code and URL without a hidden use-count read, access check or gateway acknowledgement
+     *
+     * Shared guild deadlines and cleanup apply.
+     * Only confirmed HTTP 429 rejection retries, and dispatched writes invalidate guild snapshots.
+     * After an unknown outcome, call fetchVanityUrl before deciding how to recover.
+     * Provider-side partial changes may need operator recovery and are not rolled back automatically
+     */
+    editVanityUrl(
+        guildId: string,
+        code: string | null,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<GuildVanityUrl, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Change only supplied community settings that a bot may edit.
+     * Omitted fields remain unchanged, and no old settings are fetched or merged automatically
+     *
+     * ManageGuild is required.
+     * Fluxer checks feature restrictions and constraints beyond local GuildEdit validation.
+     * Success returns the server's observed configuration, not gateway acknowledgement.
+     * Shared guild write deadlines and cancellation cleanup apply.
+     * Dispatched writes invalidate cached guild data even when the outcome is unknown.
+     * After a lost response, fetch before deciding to retry.
+     * No rollback is guaranteed
+     */
+    edit(
+        guildId: string,
+        input: GuildEdit,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<Guild, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Look up a community in the enabled guild cache, without a request or gateway connection.
+     * The result is undefined when caching is disabled or the entry is absent, expired or evicted.
+     * Cached data may be stale, so use fetch for a remote read.
+     * A hit becomes more recently used without extending expiry.
+     * An invalid ID is misuse: The default API throws GuildOperationError with reason input and the native API dies with it.
+     * A closing or closed client has no cache, so the result is undefined
+     *
+     * @remarks
+     * Returns the value synchronously.
+     * Unexpected failures throw SdkDefect
+     */
+    get(guildId: string): Guild | undefined
+    /**
+     * Fetch a community's identity and settings by decimal ID.
+     * Fluxer requires membership.
+     * The result is a frozen snapshot.
+     * This does not fetch or keep nested members, roles or channels, or infer counts or completeness
+     */
+    fetch(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<Guild, GuildOperationFailure | CancelledError | ConfigurationError>
+}