@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/reaction-pages.d.ts

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

package/dist/reaction-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaction-pages.d.ts","sourceRoot":"","sources":["../src/reaction-pages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GACf,MAAM,GACN;IACI,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,UAAU,GAAG,YAAY,CAAC,EAAE,CAAA;CAC3D,CAAA;AAEP;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,CAAA;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAA;IAC5B,mHAAmH;IACnH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,kIAAkI;IAClI,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe,EAAE,gBAAgB;CAAG;AAEpF;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC3D,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA8B,SAAQ,sBAAsB,EAAE,gBAAgB;CAAG;AAElG;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,OAAO;IAC3D,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAA;CACrD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,SAAS,GAAG,uBAAuB,GAAG,gBAAgB,CAAA"}

package/dist/reaction-pages.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reaction-pages.js.map

package/dist/reaction-pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaction-pages.js","sourceRoot":"","sources":["../src/reaction-pages.ts"],"names":[],"mappings":""}

package/dist/reactions.d.ts

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

package/dist/reactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactions.d.ts","sourceRoot":"","sources":["../src/reactions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,+GAA+G;IAC/G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IACvC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,mHAAmH;IACnH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,aAAa,GAAG,UAAU,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACpD,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACnD,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA4B,SAAQ,cAAc;IAC/D,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IACxD,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,SAAS;QACzB,0CAA0C;QAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,mCAAmC;QACnC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;KAChC,EAAE,CAAA;CACN"}

package/dist/reactions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reactions.js.map

package/dist/reactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactions.js","sourceRoot":"","sources":["../src/reactions.ts"],"names":[],"mappings":""}

package/dist/rest.d.ts

@@ -0,0 +1,260 @@
+import type { AttachmentInput } from "./attachments.js";
+import type { OperationOptions } from "./client.js";
+import type { ClientClosedError } from "./errors.js";
+import { type ApiErrorDetail } from "./api-errors.js";
+import { FluxerlyError, type OperationErrorOptions, type OperationOutcome, type OperationReason } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+/**
+ * Tune how many REST requests one client runs and queues, and the deadline an operation gets when it omits timeoutMs.
+ * Every limit is local to the client: Clients, processes and webhook or OAuth clients sharing a credential do not
+ * share these slots. Invalid values throw ConfigurationError from default createClient, naming the field, and are
+ * defects in the Effect createClient. Diagnostics report the configured capacities under rest
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@neontechspace/fluxerly"
+ * export const client = createClient({
+ *     token: "fixture-only-not-a-credential",
+ *     rest: { concurrency: 8, maxQueued: 512, defaultTimeoutMs: 15_000 },
+ * })
+ * ```
+ *
+ * @category Options
+ */
+export interface RestOptions {
+    /** Fluxer API requests, including signed attachment upload parts, that may run at once.
+     * An integer from 1 through 64. The default is 4 for each shard this client runs, up to 64, and follows the plan
+     * when automatic sharding sizes or enlarges it. A set value is used as given, whatever the shard count.
+     * Raising it does not raise Fluxer's rate limits, which still apply per route
+     * @defaultValue 4 per local shard, at most 64
+     */
+    readonly concurrency?: number;
+    /** Attachment downloads that may run at once, in slots separate from API requests so a lazy upload source can still
+     * read its own attachment. An integer from 1 through 64, default 4
+     */
+    readonly mediaConcurrency?: number;
+    /** Requests of both kinds that may wait for a slot or a rate-limit window. A request that finds the queue full fails
+     * immediately with reason busy and outcome notDispatched, and the first such failure in a minute logs rest.busy at
+     * Warn. An integer from 1 through 65,536, default 256
+     */
+    readonly maxQueued?: number;
+    /** JSON request-body bytes that waiting requests may hold together, excluding attachment transfers.
+     * A request whose JSON does not fit fails immediately with reason busy, so this also caps the largest single JSON body.
+     * An integer from 65,536 (64 KiB) through 268,435,456 (256 MiB), default 4,194,304 (4 MiB)
+     */
+    readonly queuedJsonMaxBytes?: number;
+    /** Deadline in milliseconds for a REST operation or attachment download that omits timeoutMs. It covers local
+     * queueing, rate-limit waits, retries and HTTP. An integer from 1 through 2,147,483,647, default 30,000
+     */
+    readonly defaultTimeoutMs?: number;
+}
+/**
+ * Options the gateway passes to a custom WebSocket factory for each connection it opens.
+ * A factory that uses the ws library can pass them to its constructor unchanged
+ *
+ * @category Options
+ */
+export interface WebSocketOptions {
+    /** Always false: Compression is never negotiated, so received sizes are wire sizes */
+    readonly perMessageDeflate: false;
+    /** Always false: The gateway URL is used as given and a redirect fails the connection attempt */
+    readonly followRedirects: false;
+    /** Largest accepted message in bytes. The socket must reject a larger message, including fragments, before decoding it */
+    readonly maxPayload: number;
+    /** Handshake headers to send. Contains the client's User-Agent */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/**
+ * The subset of a ws WebSocket that the gateway uses. A custom WebSocket factory returns this shape.
+ * Connection failures must arrive as error or close events, never as synchronous throws from send or the factory
+ *
+ * @category Options
+ */
+export interface WebSocketLike {
+    /** Ready state in the ws and WHATWG numbering: 0 connecting, 1 open, 2 closing, 3 closed */
+    readonly readyState: number;
+    /** Send one text frame, then call callback once, with an error when the frame could not be written */
+    send(data: string, callback: (error?: Error) => void): void;
+    /** Start a close handshake with the given WebSocket close code. The close event follows */
+    close(code: number): void;
+    /** Drop the connection immediately without a close handshake. The close event follows */
+    terminate(): void;
+    /** Receive each message with binary true for binary frames. Text arrives as bytes, as ws delivers it (a Buffer is a Uint8Array), or as a string */
+    on(event: "message", listener: (data: Uint8Array | ArrayBuffer | readonly Uint8Array[] | string, binary: boolean) => void): unknown;
+    /** Receive transport failures. An optional code identifies local receive rejections such as oversized messages */
+    on(event: "error", listener: (error: Error & {
+        code?: string;
+    }) => void): unknown;
+    /** Receive the close code once the connection has closed */
+    on(event: "close", listener: (code: number) => void): unknown;
+    /** Receive the next close once, used while waiting for a close handshake to finish */
+    once(event: "close", listener: () => void): unknown;
+    /** Remove a message listener added with on */
+    off(event: "message", listener: (data: Uint8Array | ArrayBuffer | readonly Uint8Array[] | string, binary: boolean) => void): unknown;
+    /** Remove an error listener added with on */
+    off(event: "error", listener: (error: Error & {
+        code?: string;
+    }) => void): unknown;
+    /** Remove a close listener added with on or once */
+    off(event: "close", listener: (() => void) | ((code: number) => void)): unknown;
+}
+/**
+ * Replace the HTTP and WebSocket implementations one client uses, or the User-Agent it sends.
+ * This is an advanced option for proxies, instrumentation and tests, and most bots omit it.
+ * Replacements receive every request the client makes, including instance discovery, REST, signed attachment upload
+ * parts, attachment downloads and gateway connections, so they see the bot token in Authorization headers and must
+ * protect it. The SDK keeps its own redirect, deadline, cancellation, size and rate-limit policies around them.
+ * Invalid values throw ConfigurationError from default createClient, naming the field, and are defects in the
+ * Effect createClient
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@neontechspace/fluxerly"
+ * export const client = createClient({
+ *     token: "fixture-only-not-a-credential",
+ *     transport: { userAgent: "ExampleBot/1.0 (+https://example.test/bot)" },
+ * })
+ * ```
+ *
+ * @category Options
+ */
+export interface TransportOptions {
+    /** Fetch-compatible function for every HTTP request, called without a this value. It must honour init.signal and
+     * init.redirect as the platform fetch does, and settle with a Response or reject. A rejection or synchronous throw
+     * is a network failure of that request. Defaults to the platform fetch
+     */
+    readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    /** Open one gateway WebSocket for the URL, applying every WebSocketOptions setting. It must return a WebSocketLike
+     * synchronously and report connection failures as error or close events. A synchronous throw or an unusable return
+     * value is an SDK defect. Defaults to the ws library
+     */
+    readonly webSocket?: (url: string, options: WebSocketOptions) => WebSocketLike;
+    /** User-Agent header sent with every HTTP request and gateway handshake, replacing the default
+     * `Fluxerly.js/<version> (+<SDK homepage>)`. From 1 through 512 printable ASCII characters without leading or
+     * trailing spaces
+     */
+    readonly userAgent?: string;
+}
+/**
+ * One request to a Fluxer API route that the SDK does not wrap, sent with the client's bot credential through the same
+ * queue, rate-limit learning, 429 waits, deadline, logging and cancellation as wrapped operations.
+ * Invalid input fails before dispatch with RestRequestError reason input. A GET that fails with a network error or
+ * HTTP 500, 502, 503 or 504 is retried at most twice. Another method is sent again only after Fluxer confirms a rate
+ * limit with HTTP 429, so a write with an unknown outcome is never repeated automatically.
+ * Message and resource caches are neither read nor updated, and Fluxer's rate limits and permissions still apply
+ *
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * export async function currentUserName(client: Client): Promise<string | undefined> {
+ *     const result = await client.rest.request<{ username: string }>({ method: "GET", path: "/users/@me" })
+ *     return result.isOk() ? result.value.body.username : undefined
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export interface RestRequest {
+    /** HTTP method. Only POST, PUT, PATCH and DELETE may carry a body or files */
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** API path after /v1, such as /users/@me, of at most 2,048 characters. It must start with one slash and contain
+     * only URL path characters with valid percent escapes, without empty, dot or dot-dot segments, a query or a fragment.
+     * The /v1 prefix and token-authenticated webhook routes (/webhooks/{id}/{token}) are rejected, including percent-encoded
+     * unreserved characters in those route names. These checks are case-sensitive and do not decode reserved characters.
+     * Logs, metrics and spans name the route with numeric IDs and other non-word segments replaced by placeholders
+     */
+    readonly path: string;
+    /** Query parameters appended to the path in insertion order. Undefined values are omitted, numbers must be finite,
+     * and booleans are sent as true or false. The encoded query may contain at most 8,192 characters
+     */
+    readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
+    /** JSON body, serialized when the request starts. A value JSON cannot represent fails with reason input.
+     * Its size counts against the client's queued JSON budget while the request waits. Not allowed with GET
+     */
+    readonly body?: unknown;
+    /** Files sent inline as multipart/form-data, with the JSON body as payload_json and each file as files[n] in order.
+     * Accepts the same byte, file and stream inputs as message attachments, with the same size, filename and upload-budget
+     * rules. The body must then be omitted or a JSON object without attachments, because the SDK sets attachments to
+     * the files' metadata as Fluxer's message routes expect. A request whose file source cannot be read again fails
+     * with reason rateLimit instead of waiting out a 429. Not allowed with GET
+     */
+    readonly files?: readonly AttachmentInput[];
+    /** Audit-log reason sent as the X-Audit-Log-Reason header, 1 through 512 printable ASCII characters after trimming.
+     * Omission sends no header. Never included in errors, logs or diagnostics
+     */
+    readonly auditReason?: string;
+    /** Total milliseconds across local queueing, rate-limit waits, retries and HTTP. An integer from 1 through
+     * 2,147,483,647, defaulting to the client's rest.defaultTimeoutMs (30,000 unless configured).
+     * Owned cleanup is awaited afterward, so completion can take longer
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * A default-API REST request with optional cancellation.
+ * Aborting stops waiting and cancels the HTTP exchange, but cannot undo a request Fluxer already received
+ *
+ * @category Client and lifecycle
+ */
+export interface DefaultRestRequest extends RestRequest, OperationOptions {
+}
+/**
+ * A successful response from client.rest.request, for any 2xx status
+ *
+ * @category Client and lifecycle
+ */
+export interface RestResponse<T = unknown> {
+    /** HTTP status from 200 through 299 */
+    readonly status: number;
+    /** Response headers with lower-case names. Repeated headers are joined with a comma and space as fetch does */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The parsed JSON body, or undefined when the response has no body. The type parameter is not checked at runtime,
+     * so decode the value before trusting its shape. A body over 16 MiB or one that is not valid JSON fails the request
+     * with reason response
+     */
+    readonly body: T;
+}
+/**
+ * Operation name included in REST request failures
+ *
+ * @category Errors
+ */
+export type RestOperation = "rest.request";
+/**
+ * Expected failure of client.rest.request.
+ * Reason input means the request object was invalid and nothing was sent, and reason busy means the client's local queue
+ * was full. Reason notFound means HTTP 404, and reason rejected means another non-2xx status, with the sanitized Fluxer
+ * error in apiError. Reason rateLimit means a required wait would pass the deadline or could not be completed.
+ * Reasons network, timeout and response describe transport failures, the deadline and unusable success bodies. Check outcome before repeating a write.
+ * Default API calls return it in an Err and Effect calls fail with it. Errors never include the path, query,
+ * body, headers or response body
+ *
+ * @category Errors
+ */
+export declare class RestRequestError extends FluxerlyError {
+    /** Stable expected-failure discriminator */
+    readonly _tag = "RestRequestError";
+    /** Requested operation, always rest.request */
+    readonly operation: RestOperation;
+    /** Failure category, described by {@link OperationReason} */
+    readonly reason: OperationReason;
+    /** Whether the request may have reached Fluxer, described by {@link OperationOutcome} */
+    readonly outcome: OperationOutcome;
+    /** HTTP status when a response was received, otherwise null */
+    readonly status: number | null;
+    /** Usable server-required retry wait in milliseconds, otherwise null */
+    readonly retryAfterMs: number | null;
+    /** Safe classification of why Fluxer rejected the request, or null when the response could not be classified */
+    readonly apiError: ApiErrorDetail | null;
+    /** Safe explanation of the locally invalid request field, or null when the failure was not an input failure */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Create the failure from its operation, reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options: OperationErrorOptions<RestOperation>);
+}
+/**
+ * Expected REST request failures in both APIs. Native interruption is outside this union, and default API calls
+ * additionally return CancelledError and ConfigurationError for a malformed signal
+ *
+ * @category Errors
+ */
+export type RestRequestFailure = RestRequestError | ClientClosedError;
+//# sourceMappingURL=rest.d.ts.map

package/dist/rest.d.ts.map

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

package/dist/rest.js

@@ -0,0 +1,46 @@
+import { operationErrorFields, operationErrorSettings, operationErrorText } from "./api-errors.js";
+import { FluxerlyError } from "./errors.js";
+import { freezeInputValidationDetail } from "./input-validation.js";
+/**
+ * Expected failure of client.rest.request.
+ * Reason input means the request object was invalid and nothing was sent, and reason busy means the client's local queue
+ * was full. Reason notFound means HTTP 404, and reason rejected means another non-2xx status, with the sanitized Fluxer
+ * error in apiError. Reason rateLimit means a required wait would pass the deadline or could not be completed.
+ * Reasons network, timeout and response describe transport failures, the deadline and unusable success bodies. Check outcome before repeating a write.
+ * Default API calls return it in an Err and Effect calls fail with it. Errors never include the path, query,
+ * body, headers or response body
+ *
+ * @category Errors
+ */
+export class RestRequestError extends FluxerlyError {
+    /** Stable expected-failure discriminator */
+    _tag = "RestRequestError";
+    /** Requested operation, always rest.request */
+    operation;
+    /** Failure category, described by {@link OperationReason} */
+    reason;
+    /** Whether the request may have reached Fluxer, described by {@link OperationOutcome} */
+    outcome;
+    /** HTTP status when a response was received, otherwise null */
+    status;
+    /** Usable server-required retry wait in milliseconds, otherwise null */
+    retryAfterMs;
+    /** Safe classification of why Fluxer rejected the request, or null when the response could not be classified */
+    apiError;
+    /** Safe explanation of the locally invalid request field, or null when the failure was not an input failure */
+    inputValidation;
+    /** Create the failure from its operation, reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options) {
+        const fields = operationErrorFields(options);
+        super(operationErrorText("REST request", fields), operationErrorSettings("rest", fields, options.cause));
+        this.operation = fields.operation;
+        this.reason = fields.reason;
+        this.outcome = fields.outcome;
+        this.status = fields.status;
+        this.retryAfterMs = fields.retryAfterMs;
+        this.apiError = fields.apiError;
+        this.inputValidation = freezeInputValidationDetail(fields.inputValidation);
+        this.name = this._tag;
+    }
+}
+//# sourceMappingURL=rest.js.map

package/dist/rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.js","sourceRoot":"","sources":["../src/rest.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAA;AACvH,OAAO,EAAE,aAAa,EAA2E,MAAM,aAAa,CAAA;AACpH,OAAO,EAAE,2BAA2B,EAA8B,MAAM,uBAAuB,CAAA;AAkO/F;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IAC/C,4CAA4C;IACnC,IAAI,GAAG,kBAAkB,CAAA;IAClC,+CAA+C;IACtC,SAAS,CAAe;IACjC,6DAA6D;IACpD,MAAM,CAAiB;IAChC,yFAAyF;IAChF,OAAO,CAAkB;IAClC,+DAA+D;IACtD,MAAM,CAAe;IAC9B,wEAAwE;IAC/D,YAAY,CAAe;IACpC,gHAAgH;IACvG,QAAQ,CAAuB;IACxC,+GAA+G;IACtG,eAAe,CAA8B;IAEtD,sIAAsI;IACtI,YAAY,OAA6C;QACrD,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAA;QAC5C,KAAK,CAAC,kBAAkB,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;QACxG,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;QAC3B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;QACvC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAA;QAC/B,IAAI,CAAC,eAAe,GAAG,2BAA2B,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;QAC1E,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACzB,CAAC;CACJ"}

package/dist/role-hierarchy.d.ts

@@ -0,0 +1,81 @@
+import type { Guild, GuildMember, GuildRole } from "./guilds.js";
+/** Check whether one community member outranks another using guild, member and role snapshots already held by the caller.
+ * Supply the actor who would perform the action and the target they would act on.
+ * The hierarchy.canManage function checks rank only, without fetching resources or authorizing moderation
+ *
+ * @category Roles and permissions
+ */
+export interface RoleHierarchyInput {
+    /** Community that owns the actor, target, and supplied role observations */
+    readonly guild: Guild;
+    /** Member whose hierarchy rank is being evaluated */
+    readonly actor: GuildMember;
+    /** Member the actor would need to outrank */
+    readonly target: GuildMember;
+    /** Role observations for every explicit role assigned to actor or target */
+    readonly roles: readonly GuildRole[];
+}
+/**
+ * Compare roles and members by Fluxer's role hierarchy using snapshots the caller already holds.
+ * Each method returns a plain value without fetching, retaining input or authorizing an action
+ *
+ * @category Roles and permissions
+ */
+export type HierarchyHelpers = Readonly<{
+    /**
+     * Find which of two roles ranks higher, for example when presenting or checking role order locally.
+     * Returns `1` when left is higher, `-1` when right is higher, and `0` for the same role.
+     * A larger position is higher. Tied positions use the smaller numeric role ID as higher.
+     * Malformed or cross-community snapshots throw GuildOperationError hierarchy.compare/input without retaining the input.
+     * This reports only which role ranks higher in the supplied data.
+     * It does not evaluate permissions, multi-factor authentication (MFA), membership visibility or whether a provider endpoint accepts an action
+     */
+    compare(left: GuildRole, right: GuildRole): -1 | 0 | 1;
+    /**
+     * Check whether a supplied role outranks another role, without fetching either one.
+     * Equal positions are ordered by numeric ID, with the smaller ID higher. Comparing a role with itself returns false.
+     * Malformed or cross-community snapshots throw GuildOperationError hierarchy.isAbove/input without retaining the input.
+     * This compares the supplied roles only. It does not check permissions or whether Fluxer will allow an action
+     */
+    isAbove(left: GuildRole, right: GuildRole): boolean;
+    /**
+     * Check the rank requirement for one member to manage another from supplied snapshots.
+     * The community owner and a member targeting itself pass. A non-owner cannot manage the owner.
+     * For other targets, the actor's highest explicit role must outrank the target's highest explicit role.
+     * An actor with no explicit roles fails. An actor with an explicit role outranks a target with none.
+     * The `roles` list must include one same-community observation for every actor and target role ID.
+     * The output of `roles.fetchAll` may include the implicit everyone role, which is ignored for rank comparison.
+     * Members must not list everyone as an explicit role.
+     * Malformed, incomplete, duplicate, cross-community or inconsistent snapshots throw
+     * GuildOperationError hierarchy.canManage/input without retaining the input.
+     * A true result confirms only the rank requirement and does not authorize an action.
+     * It does not check permissions, multi-factor authentication (MFA), endpoint-specific requirements, current provider
+     * membership or concurrent remote changes. To fetch fresh data and check in one call, use members.fetchCanManage
+     */
+    canManage(input: RoleHierarchyInput): boolean;
+}>;
+/**
+ * Compare roles and members by Fluxer's role hierarchy from snapshots already held, returning plain values.
+ * Invalid snapshots throw GuildOperationError with reason input
+ * @example
+ * ```ts
+ * import { hierarchy, type Client } from "@neontechspace/fluxerly"
+ * export async function hierarchyExample(client: Client, guildId: string, actorUserId: string, targetUserId: string) {
+ *     const [guild, actor, target, roles] = await Promise.all([
+ *         client.guilds.fetch(guildId),
+ *         client.members.fetch({ guildId, userId: actorUserId }),
+ *         client.members.fetch({ guildId, userId: targetUserId }),
+ *         client.roles.fetchAll(guildId),
+ *     ])
+ *     if (guild.isErr()) return guild
+ *     if (actor.isErr()) return actor
+ *     if (target.isErr()) return target
+ *     if (roles.isErr()) return roles
+ *     return hierarchy.canManage({ guild: guild.value, actor: actor.value, target: target.value, roles: roles.value })
+ * }
+ * ```
+ *
+ * @category Roles and permissions
+ */
+export declare const hierarchy: HierarchyHelpers;
+//# sourceMappingURL=role-hierarchy.d.ts.map