@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/collectors.ts

@@ -0,0 +1,81 @@
+import type { ResultAsync } from "neverthrow"
+import type { OperationOptions } from "#sdk/client"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+import type { ReactionCollectorResult, CollectorFailure, CollectorResult } from "#sdk/collectors"
+import type { Message, MessageCore } from "#sdk/messages"
+
+/**
+ * Wait for the bounded message collection created by messages.collect.
+ * Use close to end intake early and result to obtain its final result.
+ * Use `await using` to close the collector and wait for its cleanup when the enclosing block ends
+ *
+ * @category Events and collectors
+ */
+export interface Collector<M extends MessageCore = Message> {
+    /**
+     * Stop accepting messages now, keeping accepted messages for a successful partial result.
+     * Repeated calls preserve whichever terminal outcome was recorded first.
+     * Use result to await callback cleanup and read the collection
+     *
+     * @remarks
+     * Returns immediately
+     */
+    close(): void
+    /**
+     * Wait for the final frozen collection result after timer, queue, filter, listener and callback cleanup.
+     * Idle, timeout or stop can succeed with no messages or a partial collection.
+     * Collection cancellation, filter or callback failure, overflow, gateway loss and client closure fail without partial messages.
+     * Multiple or later waiters receive the same collection outcome.
+     * Cancelling this wait affects only the waiter, not collection.
+     * Keeping the handle or successful result keeps its message snapshots in memory
+     *
+     * @remarks
+     * Unexpected SDK failures reject with SdkDefect
+     */
+    result(
+        options?: OperationOptions,
+    ): ResultAsync<CollectorResult<M>, CollectorFailure | CancelledError | ConfigurationError>
+    /**
+     * Close this collector and wait for its cleanup, as `await using` does at the end of a block.
+     * The collection outcome is not rethrown here. Read it from result when it matters
+     */
+    [Symbol.asyncDispose](): Promise<void>
+}
+
+/**
+ * Wait for the reaction-addition collection created by messages.collectReactions.
+ * Use close to end intake early and result to obtain the observations.
+ * Collected additions are observations, not current votes
+ *
+ * @category Events and collectors
+ */
+export interface ReactionCollector {
+    /**
+     * Stop accepting additions now and keep accepted observations for a successful partial result.
+     * Repeated calls preserve the first recorded outcome.
+     * Use result to await callback cleanup and read the observations
+     *
+     * @remarks
+     * Returns immediately
+     */
+    close(): void
+    /**
+     * Wait for the final frozen reaction result after queue, timer, filter, listener and callback cleanup.
+     * Idle, timeout or stop can succeed with empty or partial observations.
+     * Collection cancellation, filter or callback failure, overflow, gateway loss and client shutdown fail without partial observations.
+     * Multiple or later waiters receive the same outcome.
+     * Cancelling this wait affects only the waiter, not collection.
+     * Keeping the handle or successful result retains its snapshots in memory
+     *
+     * @remarks
+     * Unexpected failures reject with SdkDefect
+     */
+    result(
+        options?: OperationOptions,
+    ): ResultAsync<ReactionCollectorResult, CollectorFailure | CancelledError | ConfigurationError>
+    /**
+     * Close this collector and wait for its cleanup, as `await using` does at the end of a block.
+     * The collection outcome is not rethrown here. Read it from result when it matters
+     */
+    [Symbol.asyncDispose](): Promise<void>
+}

package/src/api/default/commands.ts

@@ -0,0 +1,92 @@
+import { defaultCommands } from "#sdk/default-commands"
+
+/**
+ * Route prefixed messages such as !ping to registered handlers.
+ * The simplest route is runBot's commands option. For an existing client, create a router, register commands and
+ * attach it
+ *
+ * @remarks
+ * Nothing listens until attach, which uses one bounded messageCreate subscription and does not connect the client.
+ * Command handlers send replies and decide access, with optional guards, cooldowns and middleware.
+ * The router does not retry failed handlers, and a handler that returns an Err result is reported like a throw
+ *
+ * Optional groups organize names and help text, but a protected command still needs its own guard.
+ * A guard decides whether a matched command may run, and the built-in `guards` cover common checks
+ *
+ * Optional argument schemas convert raw args into frozen typed values after the guards.
+ * Conversion rejection gives rejection feedback without consuming a cooldown.
+ * The original args remain available
+ *
+ * Help pages are strings the application can send.
+ * Hiding a command in help is not an access check
+ *
+ * Creation, registration and help throw ConfigurationError for misuse, so a misconfigured router fails at startup
+ *
+ * @example
+ * ```ts
+ * import { commands, type Client } from "@neontechspace/fluxerly"
+ * export function commandGroupExample(client: Client) {
+ *     return commands
+ *         .create({ prefix: "!" })
+ *         .registerGroup({ name: "tools", aliases: ["t"] })
+ *         .register({ name: "ping", execute: ({ reply }) => reply("Pong") }, { group: ["tools"] })
+ *         .attach(client)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { commands, type Client } from "@neontechspace/fluxerly"
+ *
+ * export function installPing(client: Client) {
+ *     return commands
+ *         .create({
+ *             prefix: "!",
+ *             parse: commands.parseQuoted,
+ *             onUnmatched: ({ reply }, unmatched) => {
+ *                 if (unmatched._tag !== "CommandUnknownName") return undefined
+ *                 const hint = unmatched.suggestion === undefined ? "" : `. Closest known command: ${unmatched.suggestion}`
+ *                 return reply(`Unknown command: ${unmatched.name}${hint}`)
+ *             },
+ *         })
+ *         .register({ name: "ping", execute: ({ reply }) => reply("Pong") })
+ *         .attach(client)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { commands, type Client } from "@neontechspace/fluxerly"
+ *
+ * export function typedCommandExample(client: Client) {
+ *     return commands
+ *         .create({ prefix: "!", parse: commands.parseQuoted, onReject: "reply" })
+ *         .register({
+ *             name: "repeat",
+ *             arguments: {
+ *                 mode: { type: "choice", choices: ["fast", "slow"] },
+ *                 count: { type: "integer", min: 1, max: 5, default: 1 },
+ *                 note: { type: "text", optional: true, rest: true },
+ *             },
+ *             cooldown: { durationMs: 10_000, per: "user" },
+ *             execute: ({ reply, values }) => reply(`${values.count} / ${values.mode} / ${values.note ?? "No note"}`),
+ *         })
+ *         .attach(client)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { orThrow, type Client, type DefaultPrefixCommandRouter } from "@neontechspace/fluxerly"
+ *
+ * export async function commandHelpExample(client: Client, router: DefaultPrefixCommandRouter, channelId: string) {
+ *     const pages = router.help({ prefix: "!", maxLength: 1_000, include: (command) => command.name !== "admin" })
+ *     // Visibility is not authorization. Each command still needs its own policy
+ *     for (const content of pages) orThrow(await client.messages.send(channelId, { content, allowedMentions: {} }))
+ *     // Earlier pages remain sent if a later send fails. This example never retries
+ * }
+ * ```
+ *
+ * @category Commands
+ */
+export const commands = defaultCommands

package/src/api/default/direct-messages.ts

@@ -0,0 +1,143 @@
+import type {
+    DirectMessageChannel,
+    DirectMessageGroupEdit,
+    DirectMessageLatestMessages,
+    UserOperationFailure,
+    DefaultUserOperationOptions,
+} from "#sdk/users"
+import type { ResultAsync } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+import type { SendError } from "#sdk/message-errors"
+import type { Message, MessageCore, ReplyInput, DefaultSendOptions } from "#sdk/messages"
+
+/**
+ * Open and manage private one-to-one or group conversations with the bot's credentials.
+ * Use directMessages.send to open a conversation and send in one call, or the messages namespace when the private channel ID is known.
+ * No gateway connection is required.
+ * HTTP calls start immediately with the client's shared default deadline (rest.defaultTimeoutMs, 30,000 ms unless configured) and eligible read retries.
+ * Writes retry only confirmed rate-limit rejection, never an uncertain outcome.
+ * Abort waits for cleanup and returns CancelledError.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @category Users and DMs
+ */
+export interface DirectMessages<M extends MessageCore = Message> {
+    /**
+     * Open or reopen a one-to-one conversation with a user, then send a message.
+     * A plain string sends only that text, as shorthand for `{ content }`.
+     * The whole operation uses one deadline, and mentions are disabled by default.
+     * Message metadata and data bytes are prepared before opening the conversation.
+     * File and stream sources are captured, not copied, and read later when uploads start, using messages.send's size, upload-budget and cleanup rules.
+     * An inline multipart 429 does not replay file or stream sources.
+     * MessageError with outcome notDispatched does not mean opening the conversation was undone.
+     * A send with an unknown outcome is never repeated automatically.
+     * The opened conversation is cached under the same conditions as open.
+     * Reply references are not accepted here.
+     * Use messages.reply with an existing channel and message reference
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export async function notifyUserExample(client: Client, userId: string) {
+     *     const user = await client.users.fetch(userId)
+     *     if (user.isErr()) return user
+     *     return client.directMessages.send(user.value.id, { content: `Hello ${user.value.displayName ?? user.value.username}` })
+     * }
+     * ```
+     */
+    send(
+        userId: string,
+        input: ReplyInput | string,
+        options?: DefaultSendOptions,
+    ): ResultAsync<M, SendError | CancelledError | ConfigurationError>
+    /**
+     * Look up a private channel in the optional cache using its decimal ID, without a request.
+     * A hit may be stale and becomes more recently used without extending its age.
+     * A miss produces undefined.
+     * An invalid ID is misuse: The default API throws UserOperationError 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(id: string): DirectMessageChannel | undefined
+    /**
+     * Open or reopen a one-to-one conversation with the selected user.
+     * The result is a private channel, not proof a message can be delivered.
+     * Privacy checks can still prevent sending after opening succeeds.
+     * With the direct-message cache enabled, the channel ID is unknown until the response arrives, so some concurrent direct-message cache changes keep the result out of the cache.
+     * Examples are a directMessages.fetch call and a direct-message update event
+     */
+    open(
+        userId: string,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<DirectMessageChannel, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch a private channel by decimal ID.
+     * A community-channel response is rejected as invalid.
+     * With the direct-message cache enabled, a concurrent fetch of another private channel ID does not keep this result from being stored, unless more than 256 private channel IDs are in flight at once
+     */
+    fetch(
+        id: string,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<DirectMessageChannel, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch this bot's currently open one-to-one and group conversations.
+     * Personal notes are excluded.
+     * The list is neither an atomic snapshot nor complete message history.
+     * Enabled cache replacement is skipped when a later targeted request or channel observation conflicts
+     */
+    fetchAll(
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<readonly DirectMessageChannel[], UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch the latest messages for 1–100 selected, distinct private channel IDs through Fluxer's batch endpoint.
+     * IDs are copied by index when execution starts.
+     * This does not enumerate conversations or fill a cache.
+     * A null entry does not prove an empty channel or denied access.
+     * The omittedChannelIds field separately lists requested IDs that Fluxer did not return.
+     * Do not treat omission as null, an empty channel or denied access.
+     * The batch uses POST and is not retried after a dispatched failure with an unknown outcome, even though it reads data
+     */
+    fetchLatestMessages(
+        channelIds: readonly string[],
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<DirectMessageLatestMessages<M>, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Change supplied settings of an existing group conversation.
+     * A null name clears it, and omitted fields remain unchanged.
+     * Fluxer enforces member and owner permissions.
+     * A failed response does not guarantee rollback.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    editGroup(
+        id: string,
+        input: DirectMessageGroupEdit,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<DirectMessageChannel, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Close a one-to-one conversation for this bot, or leave a group conversation.
+     * Another recipient's conversation is not erased.
+     * If the group owner leaves, ownership may transfer.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    close(
+        id: string,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<void, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Remove a group recipient as owner, or remove the bot itself.
+     * This does not request deletion of that user's messages.
+     * If the last recipient leaves, Fluxer deletes the group.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    removeRecipient(
+        id: string,
+        userId: string,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<void, UserOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/discovery.ts

@@ -0,0 +1,103 @@
+import type {
+    DiscoveryApplication,
+    DiscoveryApplicationInput,
+    DiscoveryApplicationEdit,
+    DiscoveryCategory,
+    DiscoverySearchPage,
+    DiscoverySearchQuery,
+    DiscoveryStatus,
+} from "#sdk/discovery"
+import type { ResultAsync } from "neverthrow"
+import type { GuildOperationFailure, DefaultGuildOperationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Search Fluxer's public community directory and manage a community's directory application.
+ * This is separate from finding the instance's API and gateway endpoints.
+ * Calls start immediately without a gateway connection or directory cache.
+ * The default deadline, rest.defaultTimeoutMs (30,000 ms unless configured), includes request-capacity and rate-limit waits.
+ * Eligible GET failures retry at most twice
+ *
+ * Writes retry only confirmed HTTP 429 rejection.
+ * Input, HTTP and malformed-response failures return GuildOperationError.
+ * Client closure returns ClientClosedError.
+ * Abort waits for cleanup and returns CancelledError.
+ * Unexpected failures reject with SdkDefect.
+ * Application writes may publish or remove a listing and invalidate cached guild data.
+ * No eligibility check, approval, resubmission or joining is performed automatically.
+ * A failed write does not guarantee rollback
+ *
+ * @category Guilds and members
+ */
+export interface Discovery {
+    /**
+     * Fetch one page from the current public community directory.
+     * The limit option defaults to 24, and offset defaults to 0.
+     * Pages can change between reads, so offset-based scans are not a stable snapshot.
+     * This neither joins a community nor caches its directory entry, and needs no gateway connection.
+     * Eligible read failures are retried as described for this namespace
+     */
+    search(
+        query?: DiscoverySearchQuery,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<DiscoverySearchPage, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch a community's current directory eligibility and application state.
+     * Use a decimal guild ID with ManageGuild permission.
+     * A result with eligible false can mean discovery is disabled or the member threshold is unmet, without distinguishing them.
+     * Eligibility can change before application.
+     * Reviewed or removed applications include their available reasons
+     */
+    fetchStatus(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<DiscoveryStatus, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch directory category IDs and Fluxer's category labels in provider order.
+     * This requires an authenticated client, not membership of a particular community or ManageGuild.
+     * No category copy is kept
+     */
+    fetchCategories(
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly DiscoveryCategory[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Submit a community's application to the public directory.
+     * ManageGuild, enabled discovery and current Fluxer eligibility are required.
+     * An existing pending or approved application fails remotely.
+     * Eligible verified or partnered communities may be approved immediately.
+     * The returned stored application does not guarantee approval or search visibility.
+     * An unknown outcome may already have submitted or published the listing.
+     * Check fetchStatus before trying again
+     */
+    apply(
+        guildId: string,
+        input: DiscoveryApplicationInput,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<DiscoveryApplication, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Change supplied fields of a pending or approved directory application.
+     * ManageGuild and enabled discovery are required.
+     * At least one field must be supplied, and omitted fields remain unchanged.
+     * Tags use the input type's normalization and replacement rules.
+     * No old application is fetched or merged automatically.
+     * Updates to an approved listing can become public, while search-index updates can lag or partially fail
+     */
+    edit(
+        guildId: string,
+        input: DiscoveryApplicationEdit,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<DiscoveryApplication, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Withdraw a pending application or remove an approved directory listing.
+     * ManageGuild and enabled discovery are required.
+     * HTTP 204 succeeds with no value.
+     * A missing application is a remote error, not an assumed successful no-op.
+     * Fluxer removes the application record and may separately remove its feature or search entry.
+     * The community and its members remain, and the prior application is not restored.
+     * An unknown or partial outcome needs remote inspection and may require operator recovery, not blind replay
+     */
+    withdraw(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/emojis.ts

@@ -0,0 +1,125 @@
+import type {
+    GuildEmoji,
+    ExpressionReference,
+    ExpressionMetadata,
+    ExpressionSourceGuild,
+    EmojiCreate,
+    EmojiEdit,
+    ExpressionBatch,
+    DefaultExpressionDeleteOptions,
+} from "#sdk/expressions"
+import type { ResultAsync } from "neverthrow"
+import type { GuildOperationFailure, DefaultGuildOperationOptions, DefaultModerationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Create, list, copy, rename and delete community emoji.
+ * Use get for an optional local cache lookup, or fetchAll, fetchMetadata and fetchSource for remote reads.
+ * Shared guild request limits, deadlines and read retries apply.
+ * Writes retry only confirmed HTTP 429 rejections.
+ * Input, permission, not-found and malformed-response errors are not retried.
+ * A lost response can leave a write applied.
+ * Results are frozen snapshots, not gateway acknowledgement
+ *
+ * Expected failures return GuildOperationError or ClientClosedError.
+ * Abort returns CancelledError after cleanup.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @category Emoji and stickers
+ */
+export interface Emojis {
+    /**
+     * Look up cached emoji metadata using decimal guildId and id, without an HTTP request.
+     * The result is undefined when caching is disabled or the entry is absent, expired or invalidated by a conflicting change.
+     * 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(target: ExpressionReference): GuildEmoji | undefined
+    /**
+     * Fetch a community's emoji list in Fluxer's order, without pagination.
+     * The list can change after the response and is not an ongoing completeness guarantee.
+     * An enabled metadata cache can retain results, but not image bytes or creator accounts
+     */
+    fetchAll(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly GuildEmoji[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch minimal emoji metadata by decimal ID, without requiring source-community membership.
+     * This read does not populate the cache
+     */
+    fetchMetadata(
+        id: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<ExpressionMetadata, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch the public presentation of the community that owns a custom emoji with this decimal ID: Its ID, name, icon hash and badges.
+     * Fluxer answers when the source community is discoverable or the bot is a member of it.
+     * A private source community the bot is not in, an unavailable community or an unknown emoji fails with GuildOperationError
+     * whose apiError.code is unknownResource, without revealing which case applies.
+     * This read does not populate the cache, and the result does not update when the community changes
+     */
+    fetchSource(
+        id: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<ExpressionSourceGuild, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Upload one community emoji and return its metadata.
+     * Inputs are copied when execution starts.
+     * No image URL is fetched automatically.
+     * Fluxer checks image format, dimensions, permissions and capacity.
+     * A write with an unknown outcome is not replayed
+     */
+    create(
+        guildId: string,
+        input: EmojiCreate,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<GuildEmoji, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Upload 1–50 community emojis in one batch and return separate successes and failures.
+     * The input array is copied by index, then its entries are copied when execution starts.
+     * Some uploads can succeed while others fail.
+     * No rollback or automatic chunking is performed.
+     * Failures named by duplicate emoji names cannot be matched reliably to input positions.
+     * After an unknown outcome, fetch fresh remote data rather than blindly replaying the batch
+     */
+    createMany(
+        guildId: string,
+        input: readonly EmojiCreate[],
+        options?: DefaultModerationOptions,
+    ): ResultAsync<ExpressionBatch<GuildEmoji>, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Copy an emoji into a community by its source ID, using Fluxer's server-side copy.
+     * Source metadata is preserved.
+     * Fluxer enforces source copying restrictions
+     */
+    clone(
+        guildId: string,
+        sourceId: string,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<GuildEmoji, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Rename a community emoji without changing its image or fetching its old metadata first
+     */
+    edit(
+        target: ExpressionReference,
+        input: EmojiEdit,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<GuildEmoji, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Remove an emoji, succeeding with no value after HTTP 204.
+     * Retained metadata is invalidated.
+     * A missing target is an error, not proof of an earlier deletion.
+     * The purge option defaults to false.
+     * Setting it to true also queues irreversible media removal, subject to Fluxer's restrictions
+     */
+    delete(
+        target: ExpressionReference,
+        options?: DefaultExpressionDeleteOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+}