@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/effect/gateway.ts

@@ -0,0 +1,63 @@
+import type * as Effect from "effect/Effect"
+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
+     * Interrupting the Effect withdraws a command that is still waiting for the pacing budget and immediately releases
+     * its local queue capacity.
+     * A command already handed to the connection cannot be withdrawn. A throw from the data's own getters or toJSON
+     * dies with the thrown value, and other unexpected defects remain in the Effect cause
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client, RawDispatch } from "@neontechspace/fluxerly/effect"
+     * // 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,
+     * ) {
+     *     return Effect.gen(function* () {
+     *         // Subscribe before sending so the raw reply cannot be missed. The enclosing Scope closes it
+     *         const replies = yield* client.on("raw", (dispatch) =>
+     *             Effect.sync(() => {
+     *                 if (dispatch.t === command.replyType) onReply(dispatch)
+     *             }),
+     *         )
+     *         yield* client.gateway.send(0, command.op, command.data)
+     *         return replies
+     *     })
+     * }
+     * ```
+     */
+    send(shardId: number, op: number, d: unknown): Effect.Effect<void, GatewaySendFailure>
+}

package/src/api/effect/guards.ts

@@ -0,0 +1,194 @@
+import * as Effect from "effect/Effect"
+import type { NativePrefixCommandContext, NativePrefixCommandGuard } from "#sdk/native-commands"
+import type { PrefixCommandGuardResult } from "#sdk/commands"
+import type { PermissionName } from "#sdk/helpers"
+import type { Message, MessageCore } from "#sdk/messages"
+import { isThreadChannel, type ChannelOperationFailure } from "#sdk/channels"
+import type { GuildOperationFailure, GuildRole } from "#sdk/guilds"
+import type { UserOperationFailure } from "#sdk/users"
+import type { BotApplicationOperationFailure } from "#sdk/application"
+import {
+    applicationOwners,
+    cachedPermissionChannel,
+    fetchedPermissionChannel,
+    guardDenials,
+    inGuild,
+    missingPermissions,
+    notPrivateChannel,
+    ownerIds as validOwnerIds,
+    permissionNames,
+} from "#sdk/internal/command-guards"
+
+/**
+ * Built-in native 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
+ *
+ * @category Commands
+ */
+export interface NativeGuards {
+    /**
+     * 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>(): NativePrefixCommandGuard<never, never, 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 guard's Effect with that UserOperationFailure, which is
+     * reported with the command name
+     */
+    dmOnly<M extends MessageCore = Message>(): NativePrefixCommandGuard<UserOperationFailure, never, 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 guard's Effect with
+     * that BotApplicationOperationFailure, which is reported with the command name, and the next invocation reads again
+     */
+    ownerOnly<M extends MessageCore = Message>(): NativePrefixCommandGuard<BotApplicationOperationFailure, never, 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[],
+    ): NativePrefixCommandGuard<never, never, 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[],
+    ): NativePrefixCommandGuard<GuildOperationFailure | ChannelOperationFailure, never, M>
+}
+
+/**
+ * Built-in native command guards, namely guildOnly, dmOnly, ownerOnly and requirePermissions
+ *
+ * @example
+ * ```ts
+ * import { guards, runBot } from "@neontechspace/fluxerly/effect"
+ *
+ * export const moderationBot = (token: string | undefined) =>
+ *     runBot({
+ *         token,
+ *         commands: {
+ *             prefix: "!",
+ *             commands: {
+ *                 purge: {
+ *                     guard: [guards.guildOnly(), guards.requirePermissions(["ManageMessages"])],
+ *                     execute: ({ reply }) => reply("Purging"),
+ *                 },
+ *             },
+ *         },
+ *     })
+ * ```
+ *
+ * @category Commands
+ */
+export const guards: NativeGuards = Object.freeze({
+    guildOnly:
+        <M extends MessageCore>(): NativePrefixCommandGuard<never, never, M> =>
+        ({ message }) =>
+            Effect.succeed(inGuild(message) || { deny: guardDenials.guildOnly }),
+    dmOnly:
+        <M extends MessageCore>(): NativePrefixCommandGuard<UserOperationFailure, never, M> =>
+        ({ client, message }) =>
+            Effect.gen(function* () {
+                const denied = { deny: guardDenials.dmOnly }
+                if (inGuild(message)) return denied
+                if ((yield* client.directMessages.get(message.channelId)) !== undefined) return true
+                if ((yield* client.channels.get(message.channelId)) !== undefined) return denied
+                // A non-private answer is the expected result in a community channel and becomes the reported denial
+                return yield* client.directMessages.fetch(message.channelId).pipe(
+                    Effect.as<PrefixCommandGuardResult>(true),
+                    Effect.catchIf(notPrivateChannel, () => Effect.succeed(denied)),
+                )
+            }),
+    // The explicit-ID overload cannot fail, which this single implementation signature does not express
+    ownerOnly: (<M extends MessageCore>(
+        ...ownerIds: [] | [string | readonly string[]]
+    ): NativePrefixCommandGuard<BotApplicationOperationFailure, never, M> => {
+        const decide = (allowed: boolean): PrefixCommandGuardResult => allowed || { deny: guardDenials.ownerOnly }
+        if (ownerIds.length === 0)
+            return ({ client, message }) =>
+                Effect.suspend(() => {
+                    const known = applicationOwners.get(client)
+                    if (known !== undefined) return Effect.succeed(decide(known === message.author.id))
+                    return client.application.fetch().pipe(
+                        Effect.map(({ ownerId }) => {
+                            applicationOwners.set(client, ownerId)
+                            return decide(ownerId === message.author.id)
+                        }),
+                    )
+                })
+        const owners = validOwnerIds(ownerIds[0])
+        return ({ message }) => Effect.succeed(decide(owners.has(message.author.id)))
+    }) as NativeGuards["ownerOnly"],
+    requirePermissions: <M extends MessageCore>(
+        names: readonly PermissionName[],
+    ): NativePrefixCommandGuard<GuildOperationFailure | ChannelOperationFailure, never, M> => {
+        const required = permissionNames(names)
+        return (context) =>
+            inGuild(context.message)
+                ? memberPermissions(context).pipe(
+                      Effect.map((bits) => {
+                          if (bits === undefined) return { deny: guardDenials.unconfirmedChannel }
+                          const missing = missingPermissions(bits, required)
+                          return missing.length === 0 || { deny: guardDenials.missing(missing) }
+                      }),
+                  )
+                : Effect.succeed({ deny: guardDenials.guildOnly })
+    },
+})
+
+/**
+ * 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
+ */
+function memberPermissions<M extends MessageCore>(
+    context: NativePrefixCommandContext<M>,
+): Effect.Effect<bigint | undefined, GuildOperationFailure | ChannelOperationFailure> {
+    const { client, message } = context
+    const guildId = message.guildId!
+    const target = { guildId, userId: message.author.id }
+    const cachedOr = <A, E>(cached: Effect.Effect<A | undefined>, fetch: () => Effect.Effect<A, E>) =>
+        cached.pipe(Effect.flatMap((value) => (value === undefined ? fetch() : Effect.succeed(value))))
+    return Effect.gen(function* () {
+        const guild = yield* cachedOr(client.guilds.get(guildId), () => client.guilds.fetch(guildId))
+        const member = yield* cachedOr(client.members.get(target), () => client.members.fetch(target))
+        const cached = yield* Effect.forEach([guildId, ...member.roleIds], (id) => client.roles.get({ guildId, id }))
+        const roles = cached.every((role): role is GuildRole => role !== undefined)
+            ? cached
+            : yield* client.roles.fetchAll(guildId)
+        const readChannel = (channelId: string) =>
+            cachedOr(client.channels.get(channelId).pipe(Effect.map(cachedPermissionChannel)), () =>
+                client.channels.fetch(channelId).pipe(Effect.map(fetchedPermissionChannel)),
+            )
+        const channel = yield* 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 = yield* readChannel(channel.parentId)
+        return parentChannel && client.permissions.calculate({ guild, member, roles, channel, parentChannel })
+    })
+}

package/src/api/effect/guilds.ts

@@ -0,0 +1,247 @@
+import type { CountOperationFailure, CountOperationOptions, GuildCountsResult } from "#sdk/counts"
+import type {
+    GuildListQuery,
+    GuildListSummary,
+    GuildEdit,
+    GuildVanityUrl,
+    GuildVanityUrlUsage,
+    Guild,
+    GuildOperationFailure,
+    GuildOperationOptions,
+    ModerationOptions,
+} from "#sdk/guilds"
+import type { GuildIterationQuery, PaginationError } from "#sdk/pagination"
+import type { OwnMessageDeletionOptions } from "#sdk/messages"
+import type * as Effect from "effect/Effect"
+import type * as Stream from "effect/Stream"
+
+/** Read or change guilds and obtain gateway counts.
+ * A guild is a Fluxer community. HTTP methods return Effects and do not require a gateway connection.
+ * The REST rules below exclude fetchCounts, which requires gateway readiness and has its own documented contract
+ *
+ * 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 total deadline defaults to the client's rest.defaultTimeoutMs, 30,000 ms unless configured, including waits. Reads retry transport failures and HTTP 500/502/503/504 at most twice.
+ * Retry delays are 125–250 ms, then 250–500 ms, or a longer valid Retry-After. Confirmed HTTP 429 waits are separate and never reset the deadline
+ *
+ * Input, 404, permission failures and malformed successes do not retry. Expected failures use GuildOperationError
+ *
+ * Successful REST JSON responses are limited to 16 MiB before parsing. This is not a total memory limit. Oversized responses fail with reason response and do not retry.
+ * If a response fails after a write was sent, the write may still have applied. The SDK does not assume rollback
+ *
+ * Interruption awaits owned cleanup. Closing clients use ClientClosedError. Defects retain Cause, including cleanup failures
+ *
+ * @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
+     * The Effect uses the caller's services.
+     * Interruption waits for local cleanup but cannot cancel work already sent to Fluxer, and defects keep their Cause
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function countsExample(client: Client, guildId: string, channelId: string) {
+     *     return Effect.gen(function* () {
+     *         const guilds = yield* client.guilds.fetchCounts([guildId])
+     *         const channels = yield* client.channels.fetchMemberCounts(guildId, [channelId])
+     *         return { guilds, channels }
+     *     })
+     * }
+     * ```
+     */
+    fetchCounts(
+        guildIds: readonly string[],
+        options?: CountOperationOptions,
+    ): Effect.Effect<GuildCountsResult, CountOperationFailure>
+    /**
+     * 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 { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export const guildListExample = (client: Client) =>
+     *     client.guilds.fetchPage({ withCounts: true }).pipe(
+     *         Effect.map(page => page.map(({ id, permissions, approximateMemberCount }) => ({ id, permissions, approximateMemberCount }))),
+     *     )
+     * ```
+     */
+    fetchPage(
+        query?: GuildListQuery,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<readonly GuildListSummary[], GuildOperationFailure>
+    /**
+     * 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
+     * The returned Stream reads pages only while it is consumed.
+     * Failures end the Stream in its error channel.
+     * Interruption waits for request cleanup, and ending consumption releases the buffered page
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function guildMembershipsExample(client: Client) {
+     *     return client.guilds.iterate({ maxItems: 1000 })
+     * }
+     * ```
+     */
+    iterate(
+        query: GuildIterationQuery,
+        options?: GuildOperationOptions,
+    ): Stream.Stream<GuildListSummary, GuildOperationFailure | PaginationError>
+    /**
+     * 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?: GuildOperationOptions): Effect.Effect<void, GuildOperationFailure>
+    /**
+     * 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/effect"
+     * export const deleteOwnMessagesExample = (client: Client, channelId: string) =>
+     *     client.messages.deleteOwnMessages(channelId, { confirm: true })
+     * export const deleteOwnGuildMessagesExample = (client: Client, guildId: string) =>
+     *     client.guilds.deleteOwnMessages(guildId, { confirm: true })
+     * ```
+     */
+    deleteOwnMessages(guildId: string, options: OwnMessageDeletionOptions): Effect.Effect<void, GuildOperationFailure>
+    /**
+     * 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?: GuildOperationOptions,
+    ): Effect.Effect<GuildVanityUrlUsage, GuildOperationFailure>
+    /**
+     * 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?: ModerationOptions,
+    ): Effect.Effect<GuildVanityUrl, GuildOperationFailure>
+    /**
+     * 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?: ModerationOptions): Effect.Effect<Guild, GuildOperationFailure>
+    /**
+     * 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
+     */
+    get(guildId: string): Effect.Effect<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?: GuildOperationOptions): Effect.Effect<Guild, GuildOperationFailure>
+}