Options

AuditedRequestOptions#

interface AuditedRequestOptions extends RequestOptionsinterface AuditedRequestOptions
  extends RequestOptions

auditReason optional#

Optional audit-log reason, 1–512 printable ASCII characters after trimming

Sent only as the raw X-Audit-Log-Reason header, without URL escaping, because Fluxer does not decode escapes. Non-ASCII and control characters fail before dispatch. Omission sends no header. Never included in SDK errors or diagnostics. Header delivery does not guarantee that Fluxer stores the reason in an audit entry. Methods name the known paths that do not

string

Inherited from RequestOptions: signal, timeoutMs

CanManageOptions#

interface CanManageOptions extends RequestOptionsinterface CanManageOptions
  extends RequestOptions

actorUserId optional#

User ID of the member whose rank is checked against the target, such as the moderator who ran a command

Omit to check the bot itself. The actor must be a member of the target's community, or the read fails with notFound

string

Inherited from RequestOptions: signal, timeoutMs

ClientOptions#

interface ClientOptions<
    F extends MessageFields | undefined = undefined
>interface ClientOptions<
  F extends
    | MessageFields | undefined
    = undefined
>

cache optional#

Keep bounded, memory-only resource snapshots for local lookups

Omit this setting to retain no snapshots, without disabling REST reads or event delivery. Each category has its own client-wide budget shared across this client's shards, not a budget per shard or community. A lost gateway connection clears affected users, direct messages and messages, even after the session resumes

Community, member, role, emoji, sticker and channel snapshots stay while the shard resumes, because Fluxer replays every missed event on Resume, and are cleared whenever the shard starts a new session, including its first, so snapshots read before connecting do not outlast the first READY

Cached threads are the exception: Fluxer does not replay thread list changes, so a resumed shard's threads are cleared. Resume sends no community snapshots, so a process that resumes a session from sharding.sessions refills the enabled community, role and channel caches through REST once every shard is ready, unless sharding.refillCaches is false

When a snapshot lacks enough community context to identify its shard, the SDK clears it conservatively. Enabled message, member, role, channel and community caches also give update and delete events the snapshot they replaced, as EventContext.previous

channels optional

Cache community channels and threads from explicit reads and channel and thread events, without automatically listing them

A guild create event replaces this community's cached channels and threads with the channels and active threads the bot can view. Once a channel mutation is dispatched, the SDK removes the cached channels it can affect and prevents pending reads from restoring them

That is the written channel, with its threads when the mutation deletes the channel or converts its type, and with the forum posts that apply a tag it removes, as deleteForumTag and an edit with availableTags can, because Fluxer drops removed tags from posts without a thread update, or this community's channels for a category or a community-wide mutation such as create or reorder, or every cached channel when the cache does not hold the written channel

An operation confined to one thread removes only that thread. Bulk ordering events clear this community's cached channels because permission updates may still be in progress. Category updates or deletions also clear this community's channels because children can inherit changed permissions

Visibility loss clears the affected channel, and for a text, announcement, forum or media channel also its threads, because Fluxer deletes them without thread deletion events

A text or announcement channel update clears that channel's cached threads whose type its type cannot hold, because Fluxer retypes a converted channel's threads without thread events for archived ones

A forum or media channel update clears that channel's cached posts that apply a tag missing from the update, because Fluxer removes a tag through the channel update alone. Either update also stops pending reads from storing that channel's threads

Other pending reads by ID, and reads of other communities, still store what they return, while a pending read of the channel's own community stores nothing, as after any channel update

Thread create and update events store the thread, a thread deletion clears it, and a thread list replaces the cached threads of its community or of its listed parent channels. A change to the bot's own membership of a thread clears that thread, because its membership field is then out of date

A full list removes missing channels, never threads, only when no conflicting observation overlaps the read. These snapshots are not a complete copy of the community's channels or threads

boolean | ResourceCacheSettings<GuildChannel>| boolean
| ResourceCacheSettings<GuildChannel>

directMessages optional

Cache private conversations from explicit reads and complete channel events, without automatically listing them

A local lookup makes the item less likely to be removed for capacity, but does not extend its age limit. Targeted reads, mutations and channel events conflict only for the same conversation. Full-list reads, opening by user ID, account updates, connection gaps, clear and shutdown can prevent older responses from restoring the whole category

boolean | ResourceCacheSettings<DirectMessageChannel>| boolean
| ResourceCacheSettings<
    DirectMessageChannel
  >

emojis optional

Cache emoji metadata from REST reads and writes, not image bytes or creator accounts

A guild create event replaces this community's cached emojis with its complete list, and other community expression events clear observations. ResourceCacheSettings controls bounds and expiry, while gaps and shutdown release snapshots

boolean | ResourceCacheSettings<GuildEmoji>| boolean
| ResourceCacheSettings<GuildEmoji>

guilds optional

Cache community details from explicit reads and guild create or update events, without preloading members

Community removal or unavailability clears this community's cached resources, including channels

boolean | ResourceCacheSettings<Guild>

members optional

Cache individual memberships from explicit reads, REST pages, member add or update events and the members a guild create event lists, which are the bot's own and those in voice channels

The guild create events sent while a session starts list member accounts by ID only, so only the bot's own member, completed from READY's account, is stored from them

The member that Fluxer attaches to message create and update, reaction add and remove, and typing events refreshes it too, because Fluxer reads that member from the community's current state when it dispatches the event. It is stored whatever messageFields selects

A reaction or typing member that arrives without the user's name is completed from the member already cached before it is stored. When the member of such an event does not decode, or the whole event is rejected as malformed, the account's cached member is removed because the cached copy may now be stale

When a rejected event does not identify the account, the community's cached members are removed, and when it does not identify the community either, every cached member is. A member that fails to decode logs gateway.memberSkipped. A voice state's member is never stored, because it can lag behind role edits

The cache only receives these when Fluxer sends the events, so enabling it requests no extra dispatches and a bot that receives no such events fills it from reads alone. Member removal clears that membership. Successful or uncertain role assignment clears the target

boolean | ResourceCacheSettings<GuildMember>| boolean
| ResourceCacheSettings<GuildMember>

messages optional

Cache messages encountered in eligible REST results and gateway events, without automatically requesting history

Omission or false disables this category, while true or an options object enables it. Updates replace snapshots, while deletions and uncertain mutations remove them. A thread deletion removes the thread's messages

Deleting a text, announcement, forum or media channel also deletes its threads without thread events, so it removes the messages of every channel in that community, or without community context, that the channel cache does not hold, and every such message when the channel cache is off

Lost gateway connections clear affected entries even when the session resumes successfully. Overlapping reads and events can cause cache misses. A response that differs from an overlapping event only by lacking its community ID keeps the event snapshot. Shutdown releases this client's references, not messages still held by the application

boolean | MessageCacheOptions<NoInfer<SelectedMessage<F>>>| boolean
| MessageCacheOptions<
    NoInfer<SelectedMessage<F>>
  >

roles optional

Cache role definitions from explicit list, create or edit results and role events

Successful or uncertain creation or reordering clears this community's cached roles. Edits clear their target, or all this community's roles when changing hoistPosition. Role deletion also clears cached memberships because assignments can change without individual member events. A full list removes missing roles only when no conflicting observation overlaps the read

Partial bulk events replace only the roles they supply. A guild create event replaces this community's cached roles with its complete role list. The roles.getAll method returns a community's roles only while that list is known complete, which a full list read establishes only while the community's shard is connected

The entry limit counts the roles of every community together, so complete lists for many communities need a larger maxEntries. The cache counts bigint permission fields as decimal strings when measuring bytes

boolean | ResourceCacheSettings<GuildRole>| boolean
| ResourceCacheSettings<GuildRole>

stickers optional

Cache sticker metadata, with the same bounds, expiry and invalidation rules as emojis

boolean | ResourceCacheSettings<GuildSticker>| boolean
| ResourceCacheSettings<GuildSticker>

users optional

Cache public account profiles from explicit reads and complete user events, not partial message authors

A local lookup makes the item less likely to be removed for capacity, but does not extend its age limit. Targeted reads conflict only with later observations of the same account, so unrelated IDs can both populate. Reads without a target ID, lost gateway connections, clear and shutdown can prevent older responses from restoring the whole category

boolean | ResourceCacheSettings<User>

connection optional#

Set the startup deadline and retry limit used by both connect and run, and the recovery timing after readiness

maxStartupAttempts optional

Maximum attempts to start each local shard, including its first attempt, as a positive safe integer

The SDK retries only failures it classifies as transient, and the overall deadline can stop retries sooner. This does not limit recovery attempts after a session has become ready

number

Default 3

recovery optional

Retry timing for established-session recovery

See ConnectionRecoveryOptions

ConnectionRecoveryOptions

startupTimeoutMs optional

Total milliseconds allowed for startup, including instance discovery, retries and every local shard becoming ready

Must be an integer from 1 through 2,147,483,647. When this client owns several shards, the SDK spaces their new-session Identify commands by one second and adds one second to this deadline for each shard after the first, so the spacing alone never causes a timeout

The spacing does not coordinate quotas across processes or an IP address. An identify coordinator replaces it, and the coordinator's waits count against this deadline. Automatic sharding counts the bot's communities under a separate deadline of the same length before the shards start

Expiry stops startup work, while completion still waits for the SDK's owned-resource cleanup

number

Default 30000

gateway optional#

Gateway protocol handling and the optional fields sent in each new session's Identify

GatewayOptions

instance optional#

Select a self-hosted or other Fluxer instance instead of hosted Fluxer

Creation checks the root URL without a request. The first REST, gateway or instance.resolve operation that needs endpoints reads the unauthenticated discovery document. The client keeps those service addresses until shutdown and sends authenticated requests to them. HTTPS and WSS are required unless allowInsecure explicitly allows HTTP and WS

InstanceOptions

logging optional#

Configure this client's log output without changing another client

By default the client prints Info and higher records to the console: Startup, shard readiness, connection loss with its close code and next step, rate-limit waits of at least one second, shutdown, and application errors in full. Raise or lower the level, adjust single categories, enable Debug records or send records to an application sink. Creation copies and checks these settings without printing anything. Records never contain tokens or other credentials. Logging does not consume or replace returned operation failures

LoggingOptions

JavaScriptTypeScript

import { createClient } from "@neontechspace/fluxerly"
export function loggingExample(token) {
    return createClient({
        token,
        logging: {
            level: "info",
            categories: { rest: "debug" },
            sink: (record) => console.log(JSON.stringify(record)),
        },
    })
}

import { createClient } from "@neontechspace/fluxerly"
export function loggingExample(token: string) {
    return createClient({
        token,
        logging: {
            level: "info",
            categories: { rest: "debug" },
            sink: (record) => console.log(JSON.stringify(record)),
        },
    })
}

messageFields optional#

Choose which optional message fields the application receives

Omit this setting for full Message output. An empty array keeps id, channelId, content, author, type and guildId, where the last two are kept when the response supplies them

F

Excluded fields are absent, not undefined or empty arrays, in this client's REST, event, cache and collector results

Selecting a field includes its nested values. For example, messageSnapshots keeps its own media even when top-level media fields are excluded

This reduces the objects the SDK builds locally, not network payloads or data stored by Fluxer. The SDK still rejects malformed recognized response fields, even when they are excluded

Unknown field names and non-arrays fail with ConfigurationError whose field is messageFields. Including core field names is allowed and does not change the required core

TypeScript knows the exact selection when given a literal tuple. For an array whose contents are unknown, optional fields remain optional. The copied selection lasts for this client's lifetime and does not affect separately created webhook clients or other resource types

JavaScriptTypeScript

import { createClient } from "@neontechspace/fluxerly"
export function selectedMessagesExample(token) {
    return createClient({ token, messageFields: ["attachments", "messageReference"] })
}

import { createClient } from "@neontechspace/fluxerly"
export function selectedMessagesExample(token: string) {
    return createClient({ token, messageFields: ["attachments", "messageReference"] })
}

observe optional#

Receive structured measurements of this client's work to export as metrics or traces to any monitoring system: Each REST request attempt with its route template, status and duration, rate-limit waits, reconnection attempts, resumed sessions, and each handler and command invocation with its duration and outcome

The observer runs synchronously when the measured work finishes and is independent of the logging settings. Observations never contain tokens, payloads or message content. An observer that throws is counted in diagnostics().counters.sinkFailures without changing SDK work. The native API calls the same observer, in addition to its Effect metrics and spans. A value that is not a function fails creation with ConfigurationError

Observer

JavaScriptTypeScript

import { createClient } from "@neontechspace/fluxerly"
export function observerExample(token, record) {
    return createClient({
        token,
        observe: (observation) => {
            if (observation.type === "rest" || observation.type === "handler")
                record(observation)
        },
    })
}

import { createClient, type Observation } from "@neontechspace/fluxerly"
export function observerExample(token: string, record: (observation: Observation) => void) {
    return createClient({
        token,
        observe: (observation) => {
            if (observation.type === "rest" || observation.type === "handler") record(observation)
        },
    })
}

onError optional#

Receive every failure that has no returned result: Event handler, command, collector callback and filter, cleanup progress and cache-callback failures, subscriptions stopped by overflow, and failed state observers

The report holds the original error and IDs of the message involved, never message content. A subscription's own onError takes precedence for that subscription. Without a hook the SDK logs each failure at Error with its message, stack and cause chain. A failure only queues its report

Reports are delivered one at a time in order. Up to 256 wait while the hook is busy, and later ones are logged instead, with fields.reportOutcome "queueFull", and counted in diagnostics().counters.reportsDropped. A hook that throws or rejects is logged together with the original failure and is never retried

Shutdown does not wait for a pending hook promise. The report it was handling and any queued ones are logged at Error instead, with fields.reportOutcome "interrupted" for the report being handled and "clientClosed" for queued or later reports

(report: FailureReport) => unknown

rest optional#

Tune how many REST requests this client runs and queues, and the default operation deadline

See RestOptions for each limit and its default

RestOptions

sharding optional#

Divide community gateway traffic into numbered connections, called shards, and choose which this client owns

Omit this setting for one gateway connection, which moves to automatic sharding when Fluxer requires more shards, as described below. Omit shardIds to assign every shard in totalShards to this client. Explicit IDs are copied in the supplied order and cannot change during this client's lifetime

Use non-overlapping ID lists when another supervisor distributes shards across processes. Shard zero receives direct-message traffic, so a client handling DMs must own ID zero. A total of one uses the single-connection Identify format, without a shard tuple

"auto" | ShardingOptions

The value "auto", or totalShards "auto", sizes the plan once, at the first connect, and assigns every shard to this client. The SDK counts the bot's communities by paging GET /users/@me/guilds within startupTimeoutMs and uses one shard per 2,000 communities, from 1 through 16,384 shards

It never uses the shard count from GET /gateway/bot, which Fluxer fixes at 1. Fluxer rejects a new session with close code 4011 (sharding required) when that one shard holds more than 2,500 communities (MAX_GUILDS_PER_SHARD in fluxer_gateway/src/gateway/gateway_sharding.erl)

Community IDs do not split evenly across shards, so the lower target keeps every shard below that ceiling and leaves room to grow. Until that count completes, client.shards and diagnostics().shards are empty and community routing treats every community as unowned

A failed count fails startup like a connection failure: A rejected token with AuthenticationError, an exhausted rate limit with RateLimitError, the deadline with ConnectionTimeoutError and other failures with ConnectionError whose phase is discovery, including a community list page that does not move past the previous one

When the bot grows and Fluxer closes a shard with 4011 while the client runs, the SDK counts the communities again and moves every shard to a larger plan in the same process: The plan for the new count, or one shard more when the count still fits the old total

Every shard then starts a new session under the new total, so events sent during the switch are missed and community-scoped caches refill from the new sessions. The SDK logs lifecycle.resharded at Warn with the old and new totals and keeps running

A failed count during a move ends the client with the same errors as a failed count at startup. After 3 such moves within an hour, or at 16,384 shards, a further 4011 ends the client with a ConnectionError as an explicit total does. Automatic sizing suits one process that owns every shard

Processes that split shards need an explicit total

A client without this setting makes the same move from its one shard when Fluxer closes it with 4011, so a bot that outgrows one connection keeps running instead of failing. Once the bot is in more than 2,500 communities, each start first opens a session that Fluxer rejects, which the value "auto" avoids. An explicit total, including totalShards 1, never moves

token#

Bot token used to authenticate requests and gateway connections, commonly read from the process environment

Undefined is accepted so an environment value can be passed directly. Creation requires a non-blank string and otherwise fails with ConfigurationError, whose hint names an unset environment variable as the likely cause. Surrounding whitespace and one pair of matching quotes, which .env files often add, are removed. A value that starts with a Bot or Bearer scheme is rejected, since the SDK adds the Bot scheme itself. Only Fluxer can establish whether the token is valid

string | undefined

transport optional#

Replace the HTTP and WebSocket implementations or the User-Agent this client sends

This is an advanced option for proxies, instrumentation and tests. See TransportOptions

TransportOptions

uploads optional#

Bound the attachment transfer bytes reserved by queued and active upload operations

maxBytes optional

Maximum reserved attachment transfer bytes across queued and active operations, as a positive safe integer

Defaults to 104,857,600 (100 MiB), separate from the rest.queuedJsonMaxBytes queued JSON budget (4 MiB by default). The SDK reserves accepted byte-array lengths, file sizes or declared stream sizes before waiting for a request slot. A new operation fails with busy if its reservation would exceed this limit. Reservations remain held across rate-limit retries and release after transport cleanup. This excludes caller buffers, metadata and runtime overhead, so it is not a JavaScript heap or process-memory ceiling

number

ConnectionRecoveryOptions#

interface ConnectionRecoveryOptions

attemptTimeoutMs optional#

Time allowed for one recovery attempt in milliseconds, covering discovery, the handshake and Identify or Resume, an integer from 1,000 through 2,147,483,647

An attempt that runs out fails and is retried

number

Default 30000

healthyResetMs optional#

Continuous connected time in milliseconds after which the next connection loss restarts the backoff sequence from minDelayMs, an integer from 1,000 through 2,147,483,647

Socket cleanup never counts as connected time

number

Default 60000

maxDelayMs optional#

Largest backoff ceiling in milliseconds, an integer from minDelayMs through 2,147,483,647

Defaults to 30,000, or to minDelayMs when that is larger

number

Default 30000

minDelayMs optional#

Ceiling for the first recovery retry in milliseconds, an integer from 100 through 2,147,483,647

number

Default 1000

ExpressionDeleteOptions#

interface ExpressionDeleteOptions extends AuditedRequestOptionsinterface ExpressionDeleteOptions
  extends AuditedRequestOptions

purge optional#

False/default removes the community entry without asking to purge its image

True additionally requests irreversible queued asset/CDN removal and requires Fluxer's expression-purge feature. HTTP success does not mean the purge job has finished. Failure after dispatch can leave either effect applied

boolean

Inherited from AuditedRequestOptions: auditReason, signal, timeoutMs

GatewayOptions#

interface GatewayOptions

flags optional#

Identify session flags

Omission sets none. Creation rejects other keys and non-boolean values

debounceMessageReactions optional

Ask Fluxer to merge runs of reaction additions in direct messages and group direct messages into one messageReactionAddMany event (MESSAGE_REACTION_ADD_MANY) instead of many messageReactionAdd events

Community reactions always arrive individually. This is Fluxer's DEBOUNCE_MESSAGE_REACTIONS flag, value 2. Defaults to false

boolean

ignoredEvents optional#

Dispatch types Fluxer should not send to this client's sessions, to save bandwidth and decoding

Omission suppresses nothing. An array lists upper-case dispatch names such as TYPING_START or PRESENCE_UPDATE: Names may use letters, digits and underscores up to 64 characters, are upper-cased and deduplicated, and the list may hold at most 256 names that encode to at most 2,560 bytes, keeping Identify within Fluxer's 4,096-byte limit

Creation rejects READY, RESUMED and the request replies GUILD_MEMBERS_CHUNK, RATE_LIMITED, GUILD_COUNTS_UPDATE and CHANNEL_MEMBER_COUNTS_UPDATE, and any type an enabled cache category needs to stay current, with ConfigurationError

Fluxer still delivers MESSAGE_CREATE for a message that directly mentions the bot, @here or @everyone, but not merely for a role mention, a direct message or a message the bot authored. A suppressed dispatch uses no sequence number

MESSAGE_REACTION_ADD_MANY batches are generated from unsuppressed MESSAGE_REACTION_ADD dispatches, so ignoring ADD prevents batches, while ignoring MANY alone does not. The list is fixed for each session, so changing an explicit list needs a new client. Resume retains the session's filtering

Registering an event whose source dispatch types are all suppressed receives nothing, apart from the message mention exceptions, and each new session logs gateway.ignoredEventRegistered at Warn for such registrations

readonly string[] | "auto"

The value "auto" computes the list at each new-session Identify from the events registered at that moment, through on, subscribe, waitFor, collectors and command routers: Every dispatch type that delivers no registered event is suppressed, except those enabled cache categories, presence member selection (GUILD_CREATE) and cache clearing (GUILD_DELETE) need, READY, RESUMED, request replies and types this SDK version does not decode

MESSAGE_REACTION_ADD and MESSAGE_REACTION_REMOVE are always kept, because reaction pages started after Identify read clicks from them, so bots in busy guilds save less than the registrations alone suggest. A raw subscriber disables suppression entirely

The tradeoff: A handler registered after a session started does not receive suppressed types until that shard's next new session, which a Resume does not start, so register handlers before connecting. A messageReactionAddMany registration keeps MESSAGE_REACTION_ADD for Fluxer's batch generator

Cache categories keep their dispatch types whether or not an event is registered, so enabled caches reduce the savings

onMalformedDispatch optional#

What to do when Fluxer sends a known dispatch that fails validation

The default, skip, drops that event, logs gateway.dispatchRejected at Warn with the dispatch type and failing field path, clears cache entries it could have changed and keeps the session running. When the dispatch lacks a usable channel or community ID, the entries it could have changed are found by message ID or cleared more widely. The value terminate ends the shard with a protocol ConnectionError instead, without the new-session retry that other invalid gateway data gets

"skip" | "terminate"

presence optional#

Initial presence: The status each new session's Identify carries, and the first presence intent, as if presence.set were called with it before connecting

A later presence.set replaces it, and later new sessions then Identify with the latest accepted presence. Because Fluxer may prefer the account's saved status to an Identify presence, the SDK also publishes the intent with a presence update after READY or RESUMED, as for presence.set. Creation validates it like presence.set and fails with ConfigurationError for invalid input. Omission sends no Identify presence, so Fluxer uses the account's saved status

PresenceInput

InstanceOptions#

interface InstanceOptions

allowInsecure optional#

Permit HTTP and WS endpoints only for an explicitly selected local or self-hosted instance

Defaults to false

boolean

url#

Absolute HTTPS root URL that publishes /.well-known/fluxer, such as https://fluxer.example

A path beyond /, query, fragment or embedded credentials is invalid. HTTP requires allowInsecure, and omitting the whole instance option selects hosted Fluxer

string

OperationOptions#

interface OperationOptions

signal optional#

Pass an AbortController's signal to cancel this operation and await its required cleanup

An already-aborted signal cancels before the operation takes ownership. For connect it controls startup only, so aborting after READY does not close the established connection. For an accepted run it controls the full client lifetime, but waitForClose cancels only that observer

Cancellation cannot undo a dispatched server mutation, and a later abort cannot undo completed work. A malformed signal returns ConfigurationError with field signal before work starts, or on a lazy iterator's first next

Throwing signal accessors or listener methods are application faults rather than typed input failures, rejected as SdkDefect with code application.defect and the thrown value as its cause. Shutdown does not accept a signal

OperationSignal

OperationSignal#

interface OperationSignal

aborted#

Whether cancellation has already been requested

boolean

addEventListener(
    type: "abort",
    listener: () => void,
    options?: { once?: boolean }
): voidaddEventListener(
  type: "abort",
  listener: () => void,
  options?: { once?: boolean }
): void

removeEventListener(type: "abort", listener: () => void): voidremoveEventListener(
  type: "abort",
  listener: () => void
): void

OwnMessageDeletionOptions#

interface OwnMessageDeletionOptions extends RequestOptionsinterface OwnMessageDeletionOptions
  extends RequestOptions

confirm#

Must be true to acknowledge that the deletion is irreversible and cannot be rolled back

true

Inherited from RequestOptions: signal, timeoutMs

PaginationQuery#

interface PaginationQuery

maxItems#

Maximum items to deliver, a required positive safe integer

Reaching this cap finishes normally, without proving remote exhaustion

number

maxPages optional#

Maximum page requests, a positive safe integer

Defaults to the pages maxItems needs at pageSize plus 100 spare pages for short pages and skipped duplicates, so a caller who sets only maxItems is not stopped by the page count when pages are full. The default stays finite, so a server that returns far less than asked still ends with pageLimit

Set a lower value to cap requests. Retrying a request for the same page does not use another page allowance. Duplicate-only pin pages do count. Needing a further page after this allowance fails with PaginationError reason pageLimit, preserving already-delivered items

number

pageSize optional#

Maximum items to request per page, reduced when fewer items remain under maxItems

History defaults to 50 with a range of 1 through 100, members to 100 with 1 through 1,000. Community memberships default to 200 with 1 through 200, reaction users to 25 with 1 through 100. Pins default to 50 with 1 through 50, audit logs to 50 with 1 through 100. Member search defaults to 100 with 1 through 100, message search to 25 with 1 through 25

number

PermissionFetchOptions#

interface PermissionFetchOptions extends RequestOptionsinterface PermissionFetchOptions
  extends RequestOptions

preferCache optional#

Read each observation from an enabled cache before fetching it, such as to decide for every command without a request

Default false, which fetches every observation fresh. The guild, member and channel come from their caches when present, and the roles when the everyone role and every member role are all cached, otherwise one list read replaces all of them

A cached channel without its overwrite list is fetched, and a thread's parent channel is read the same way. Only fetches count toward the deadline. Cached observations reflect the last applied gateway events, so they can differ from Fluxer, and their snapshots can come from different moments

Cached entries stay while a shard can resume and are cleared when a new session starts, after which they are fetched. Use the default right before an action where a stale grant matters. With the caches disabled, the call behaves as it does by default

A value that is not a boolean fails with reason input

boolean

Inherited from RequestOptions: signal, timeoutMs

RequestOptions#

interface RequestOptions extends OperationOptionsinterface RequestOptions
  extends OperationOptions

timeoutMs optional#

Total milliseconds for this call, an integer from 1 through 2,147,483,647

For a bot client's REST calls it covers local queueing, rate-limit waits, retries and HTTP, and defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured. Calls outside a bot client's REST settings, such as standalone webhook clients, OAuth, instance discovery and gateway counts, default to 30,000. Owned cleanup is awaited afterward, so the call can finish later than this deadline

number

Inherited from OperationOptions: signal

RestOptions#

interface RestOptions

import { createClient } from "@neontechspace/fluxerly"
export const client = createClient({
    token: "fixture-only-not-a-credential",
    rest: { concurrency: 8, maxQueued: 512, defaultTimeoutMs: 15_000 },
})

import { createClient } from "@neontechspace/fluxerly"
export const client = createClient({
    token: "fixture-only-not-a-credential",
    rest: { concurrency: 8, maxQueued: 512, defaultTimeoutMs: 15_000 },
})

concurrency optional#

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

number

Default 4 per local shard, at most 64

defaultTimeoutMs optional#

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

number

maxQueued optional#

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

number

mediaConcurrency optional#

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

number

queuedJsonMaxBytes optional#

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)

number

RunBotOptions#

interface RunBotOptions

drainMs optional#

Milliseconds that a requested stop lets running work finish before cancelling it, default 5,000

A stop is requested by the signal option or, with processSignals enabled, by SIGINT or SIGTERM. The bot then accepts no new events, while running handlers and commands, events already waiting for them and REST requests continue until they finish or the time runs out. Then the bot shuts down as usual

The default fits within the 10 seconds that common process managers, such as Docker, wait before force-stopping a process. Pass a larger value when the platform waits longer, or 0 to cancel running handlers at once. A stop caused by a failure does not drain. See ShutdownOptions for the details of a drain

Accepts an integer from 0 through 2,147,483,647, and another value throws ConfigurationError

number

processSignals optional#

Handle SIGINT and SIGTERM for this run only, as a requested stop that drains for drainMs

The handlers are added when the run starts and removed once its cleanup finishes, and the runner never exits the process. The default API enables this unless the option is false. The Effect API enables it only when the option is true, because a launcher such as NodeRuntime.runMain already interrupts the program on these signals

Each signal is handled once, so sending the same signal again, such as a second Ctrl+C, ends the process at once with Node.js's default behavior instead of waiting for the drain

boolean

reportFailure optional#

Report a failed run for the process, enabled by default

When the bot stops because of a failure, runBot logs that failure once as an Error record with code lifecycle.botFailed, unless the client already logged the same error, and sets process.exitCode to 1 so the process exits with a failure status. The failure is still returned as well

Reports before client creation use the configured logging settings and mask the token after removing surrounding whitespace and one pair of matching quotes. Unusable logging settings fall back to the entry point's default output. In the native API, a throwing option getter does not discard readable token, logging or reportFailure settings

An unreadable reportFailure setting keeps reporting enabled. Default API misuse and option-getter failures throw synchronously without a runner report or exit-status change. A normal stop and an interruption report nothing. Set false when the application handles the returned failure and owns the exit status itself

boolean

signal optional#

Stop and close the bot when this signal aborts, as a normal stop

If already aborted, the configuration is still checked and misuse is still reported, but no client is created and the run succeeds at once

OperationSignal

TimeoutOptions#

interface TimeoutOptions extends AuditedRequestOptionsinterface TimeoutOptions
  extends AuditedRequestOptions

timeoutReason optional#

Optional timeout audit metadata

Null or omission sends no meaningful reason. A string must contain 1–512 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming. The original string is sent unchanged

string | null

Inherited from AuditedRequestOptions: auditReason, signal, timeoutMs

TimeoutStateOptions#

interface TimeoutStateOptions

now optional#

Moment to evaluate the timeout at, such as to test a snapshot or a future time

Default the wall time of the Clock that the client was created with

Date

TransportOptions#

interface TransportOptions

import { createClient } from "@neontechspace/fluxerly"
export const client = createClient({
    token: "fixture-only-not-a-credential",
    transport: { userAgent: "ExampleBot/1.0 (+https://example.test/bot)" },
})

import { createClient } from "@neontechspace/fluxerly"
export const client = createClient({
    token: "fixture-only-not-a-credential",
    transport: { userAgent: "ExampleBot/1.0 (+https://example.test/bot)" },
})

fetch optional#

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

(url: string, init: RequestInit) => Promise<Response>(url: string, init: RequestInit)
  => Promise<Response>

userAgent optional#

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

string

webSocket optional#

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

(url: string, options: WebSocketOptions) => WebSocketLike(
  url: string,
  options: WebSocketOptions
) => WebSocketLike

WebSocketLike#

interface WebSocketLike

readyState#

Ready state in the ws and WHATWG numbering: 0 connecting, 1 open, 2 closing, 3 closed

number

close(code: number): void

off(
    event: "message",
    listener: (
        data:
            | string
            | ArrayBuffer
            | Uint8Array<ArrayBufferLike>
            | readonly Uint8Array<ArrayBufferLike>[],
        binary: boolean
    ) => void
): unknownoff(
  event: "message",
  listener: (
    data:
      | string
      | ArrayBuffer
      | Uint8Array<ArrayBufferLike>
      | readonly Uint8Array<
          ArrayBufferLike
        >[],
    binary: boolean
  ) => void
): unknown

off(
    event: "error",
    listener: (error: Error & { code?: string }) => void
): unknownoff(
  event: "error",
  listener: (
    error:
      & Error
      & { code?: string }
  ) => void
): unknown

off(
    event: "close",
    listener: (() => void) | ((code: number) => void)
): unknownoff(
  event: "close",
  listener:
    | (() => void)
    | ((code: number) => void)
): unknown

on(
    event: "message",
    listener: (
        data:
            | string
            | ArrayBuffer
            | Uint8Array<ArrayBufferLike>
            | readonly Uint8Array<ArrayBufferLike>[],
        binary: boolean
    ) => void
): unknownon(
  event: "message",
  listener: (
    data:
      | string
      | ArrayBuffer
      | Uint8Array<ArrayBufferLike>
      | readonly Uint8Array<
          ArrayBufferLike
        >[],
    binary: boolean
  ) => void
): unknown

on(
    event: "error",
    listener: (error: Error & { code?: string }) => void
): unknownon(
  event: "error",
  listener: (
    error:
      & Error
      & { code?: string }
  ) => void
): unknown

on(event: "close", listener: (code: number) => void): unknownon(
  event: "close",
  listener: (code: number) => void
): unknown

once(event: "close", listener: () => void): unknownonce(
  event: "close",
  listener: () => void
): unknown

send(data: string, callback: (error?: Error) => void): voidsend(
  data: string,
  callback: (error?: Error) => void
): void

terminate(): void

WebSocketOptions#

interface WebSocketOptions

followRedirects#

Always false: The gateway URL is used as given and a redirect fails the connection attempt

false

headers#

Handshake headers to send

Contains the client's User-Agent

Readonly<Record<string, string>>

maxPayload#

Largest accepted message in bytes

The socket must reject a larger message, including fragments, before decoding it

number

perMessageDeflate#

Always false: Compression is never negotiated, so received sizes are wire sizes

false

WebhookMessageOperationOptions#

interface WebhookMessageOperationOptions extends RequestOptionsinterface WebhookMessageOperationOptions
  extends RequestOptions

threadId optional#

Decimal ID of the thread that holds the message, sent as the thread_id query parameter

Set it for a message in a thread, because Fluxer looks in the webhook's channel otherwise and answers that the message is unknown. Fluxer rejects a thread that belongs to another channel

string

Inherited from RequestOptions: signal, timeoutMs