Client and Lifecycle

createClient#

createClient<
    F extends MessageFields | undefined = undefined
>(options: ClientOptions<F>): Client<SelectedMessage<F>>createClient<
  F extends
    | MessageFields | undefined
    = undefined
>(
  options: ClientOptions<F>
): Client<SelectedMessage<F>>

import { createClient } from "@neontechspace/fluxerly"

export function shardingExample(token) {
    return createClient({ token, sharding: { totalShards: 4, shardIds: [0, 2] } })
}

import { createClient } from "@neontechspace/fluxerly"

export function shardingExample(token: string) {
    return createClient({ token, sharding: { totalShards: 4, shardIds: [0, 2] } })
}

defineBot#

defineBot<
    F extends MessageFields | undefined = undefined,
    S extends Readonly<Record<string, unknown>>
        = Readonly<
            Record<
                string,
                | Readonly<
                      Record<string, CommandArgumentDescriptor>
                  >
                | undefined
            >
        >
>(
    options: Omit<BotOptions<F, S>, "token">
): Omit<BotOptions<F, S>, "token">defineBot<
  F extends
    | MessageFields | undefined
    = undefined,
  S extends Readonly<
    Record<string, unknown>
  >
    = Readonly<
      Record<
        string,
        | Readonly<
            Record<
              string,
              CommandArgumentDescriptor
            >
          >
        | undefined
      >
    >
>(
  options:
    Omit<BotOptions<F, S>, "token">
): Omit<BotOptions<F, S>, "token">

import { defineBot, runBot } from "@neontechspace/fluxerly"

// A test imports bot and passes it to createTestBot from @neontechspace/fluxerly/testing
export const bot = defineBot({
    commands: {
        prefix: "!",
        commands: {
            greet: {
                arguments: { name: { type: "text", rest: true } },
                execute: ({ reply, values }) => reply(`Hello, ${values.name}!`),
            },
        },
    },
})

// Running this file starts the bot, while importing it from a test does not
if (import.meta.main)
    await runBot({ token: process.env.FLUXER_BOT_TOKEN, ...bot })

import { defineBot, runBot } from "@neontechspace/fluxerly"

// A test imports bot and passes it to createTestBot from @neontechspace/fluxerly/testing
export const bot = defineBot({
    commands: {
        prefix: "!",
        commands: {
            greet: {
                arguments: { name: { type: "text", rest: true } },
                execute: ({ reply, values }) => reply(`Hello, ${values.name}!`),
            },
        },
    },
})

// Running this file starts the bot, while importing it from a test does not
if (import.meta.main) await runBot({ token: process.env.FLUXER_BOT_TOKEN, ...bot })

runBot#

runBot<
    F extends MessageFields | undefined = undefined,
    S extends Readonly<Record<string, unknown>>
        = Readonly<
            Record<
                string,
                | Readonly<
                      Record<string, CommandArgumentDescriptor>
                  >
                | undefined
            >
        >
>(options: BotOptions<F, S>): ResultAsync<
    void,
    | ConfigurationError | CriticalWorkerStoppedError
    | CancelledError | ApplicationError | ConnectError
>runBot<
  F extends
    | MessageFields | undefined
    = undefined,
  S extends Readonly<
    Record<string, unknown>
  >
    = Readonly<
      Record<
        string,
        | Readonly<
            Record<
              string,
              CommandArgumentDescriptor
            >
          >
        | undefined
      >
    >
>(
  options: BotOptions<F, S>
): ResultAsync<
  void,
  | ConfigurationError
  | CriticalWorkerStoppedError
  | CancelledError
  | ApplicationError | ConnectError
>

import { runBot } from "@neontechspace/fluxerly"

export function pingBot(token) {
    return runBot({
        token,
        commands: {
            prefix: "!",
            commands: {
                ping: { execute: ({ reply }) => reply("Pong!") },
                roll: {
                    arguments: { sides: { type: "integer", min: 2, max: 100, default: 6 } },
                    execute: ({ reply, values }) => reply(`${1 + Math.floor(Math.random() * values.sides)}`),
                },
            },
        },
    })
}

import { runBot } from "@neontechspace/fluxerly"

export function pingBot(token: string | undefined) {
    return runBot({
        token,
        commands: {
            prefix: "!",
            commands: {
                ping: { execute: ({ reply }) => reply("Pong!") },
                roll: {
                    arguments: { sides: { type: "integer", min: 2, max: 100, default: 6 } },
                    execute: ({ reply, values }) => reply(`${1 + Math.floor(Math.random() * values.sides)}`),
                },
            },
        },
    })
}

BotApplication#

interface BotApplication

botPublic#

Whether Fluxer currently permits non-owners to install this bot

boolean

botRequireCodeGrant#

Whether Fluxer currently requires its OAuth2 code-grant flow for this bot

boolean

description#

Provider's application description, sourced from the bot bio and null when absent

string | null

icon#

Provider's application icon hash, null when the bot has no avatar

string | null

id#

Decimal application ID, suitable for links.installation

string

name#

Provider application name

string

ownerId#

Decimal user ID of the account that owns the application, the ID that guards.ownerOnly() allows when called without IDs

string

BotEventOptions#

interface BotEventOptions<
    K extends EventName,
    M extends MessageCore = Message
>
    extends HandlerOptions<EventMap<M>[K]>interface BotEventOptions<
  K extends EventName,
  M extends MessageCore = Message
>
  extends HandlerOptions<
    EventMap<M>[K]
  >

handler#

Called for each event

BotEventHandler<K, M>

onError optional#

Receive this handler's failures instead of the client-level onError

(report: FailureReport) => unknown

partitionReady optional#

Hold the events of a partition key until its own setup is done, as the client.on option partitionReady does

Valid only together with partition, otherwise runBot throws ConfigurationError before any client exists

(key: string, signal: AbortSignal) => unknown(key: string, signal: AbortSignal)
  => unknown

Inherited from HandlerOptions: concurrency, maxPendingBytes, maxPendingMessages, overflow, partition

BotOptions#

interface BotOptions<
    F extends MessageFields | undefined = undefined,
    S extends Readonly<Record<string, unknown>>
        = Readonly<
            Record<string, CommandArgumentSchema | undefined>
        >
>
    extends ClientOptions<F>, RunBotOptionsinterface BotOptions<
  F extends
    | MessageFields | undefined
    = undefined,
  S extends Readonly<
    Record<string, unknown>
  >
    = Readonly<
      Record<
        string,
        | CommandArgumentSchema
        | undefined
      >
    >
>
  extends ClientOptions<
    F
  >, RunBotOptions

commands optional#

Prefix commands registered and attached before connecting

See BotCommandsOptions

BotCommandsOptions<SelectedMessage<F>, S>BotCommandsOptions<
  SelectedMessage<F>, S
>

events optional#

Handlers registered before connecting and closed when the bot stops

Own enumerable entries are read once when runBot is called. Undefined handlers are skipped. Pass a function, or an object with a handler and its own delivery settings. By default messageCreate and partitioned handlers run up to 8 callbacks at a time and other events 1. When a queue fills, the oldest waiting event is dropped with a Warn record, and the bot keeps running. With a partition, the overflow option's rule decides which event is dropped. Bot-authored messageCreate and messageUpdate events skip these handlers unless ignoreBots is false

BotEvents<SelectedMessage<F>>

ignoreBots optional#

Skip messageCreate and messageUpdate events whose author is a bot, including this bot's own messages, before they reach the events handlers or prefix commands

Defaults to true, so a reply cannot trigger its own handler. Set false for a bridge or logging bot that handles every message, and check message.author.isBot where needed. Prefix commands follow the same setting unless commands.ignoreBots sets its own. A value other than a boolean throws ConfigurationError

boolean

setup optional#

Startup work after events and commands are registered and before the gateway connects, such as extra subscriptions, cache warm-up or scheduled tasks

The bot connects only after a returned promise settles, so no handler runs before setup finishes. Start timers and background work with client.schedule, whose tasks belong to the bot: A requested stop lets their running work finish within drainMs, every stop cancels the rest, and a failure reaches onError or the log. The signal aborts when the bot begins stopping for any reason, including a requested stop before its drain, a failure and a stop while setup is still running. Pass it to SDK operations, or listen for its abort event to end other work started here, which the runner does not track or await. A throw, rejection or returned or resolved Err result stops the bot before connecting, and runBot returns an Err ApplicationError whose source is "runBot setup" and whose cause is the original value, such as the GuildOperationError of a failed read. A thrown SdkDefect remains a defect and rejects with SdkDefect. The Effect API runs setup in the bot's Scope instead, so its finalizers and scoped fibers end with the bot

(
    client: Client<SelectedMessage<F>>,
    context: { readonly signal: AbortSignal }
) => unknown(
  client: Client<SelectedMessage<F>>,
  context: {
    readonly signal: AbortSignal
  }
) => unknown

Inherited from ClientOptions: cache, connection, gateway, instance, logging, messageFields, observe, onError, rest, sharding, token, transport, uploads

Inherited from RunBotOptions: drainMs, processSignals, reportFailure, signal

CurrentBotApplication#

interface CurrentBotApplication

import { links } from "@neontechspace/fluxerly"
export async function applicationExample(client) {
    const application = await client.application.fetch()
    return application.isErr() ? application : links.installation(application.value.id, { permissions: 0n })
}

import { links, type Client } from "@neontechspace/fluxerly"
export async function applicationExample(client: Client) {
    const application = await client.application.fetch()
    return application.isErr() ? application : links.installation(application.value.id, { permissions: 0n })
}

fetch(options?: RequestOptions): ResultAsync<
    BotApplication,
    | ConfigurationError | BotApplicationOperationFailure
    | CancelledError
>fetch(
  options?: RequestOptions
): ResultAsync<
  BotApplication,
  | ConfigurationError
  | BotApplicationOperationFailure
  | CancelledError
>

CustomStatusInput#

interface CustomStatusInput

emoji optional#

An explicit custom-emoji ID or one Unicode emoji

CustomStatusEmoji

expiresAt optional#

Future ISO-8601 expiration time

Impossible calendar dates are rejected before retaining the update. Fluxer rejects an expiry that passes before it receives the update

string

text optional#

Status text, from 1 through 128 UTF-16 code units

string

GatewayCommands#

interface GatewayCommands

send(
    shardId: number,
    op: number,
    d: unknown,
    options?: OperationOptions
): ResultAsync<
    void,
    ConfigurationError | CancelledError | GatewaySendFailure
>send(
  shardId: number,
  op: number,
  d: unknown,
  options?: OperationOptions
): ResultAsync<
  void,
  | ConfigurationError
  | CancelledError
  | GatewaySendFailure
>

// Commands with an SDK method, such as community counts through client.guilds.fetchCounts, use that method instead
export async function sendCustomCommand(client, command, onReply) {
    // Subscribe before sending so the raw reply cannot be missed
    const replies = client.on("raw", (dispatch) => {
        if (dispatch.t === command.replyType)
            onReply(dispatch)
    })
    try {
        const result = await client.gateway.send(0, command.op, command.data)
        if (result.isErr())
            replies.close()
        // Close the returned subscription once the reply has arrived
        return result.map(() => replies)
    }
    catch (error) {
        replies.close()
        throw error
    }
}

import type { Client, RawDispatch } from "@neontechspace/fluxerly"
// Commands with an SDK method, such as community counts through client.guilds.fetchCounts, use that method instead
export async function sendCustomCommand(
    client: Client,
    command: { op: number; data: unknown; replyType: string },
    onReply: (reply: RawDispatch) => void,
) {
    // Subscribe before sending so the raw reply cannot be missed
    const replies = client.on("raw", (dispatch) => {
        if (dispatch.t === command.replyType) onReply(dispatch)
    })
    try {
        const result = await client.gateway.send(0, command.op, command.data)
        if (result.isErr()) replies.close()
        // Close the returned subscription once the reply has arrived
        return result.map(() => replies)
    } catch (error) {
        replies.close()
        throw error
    }
}

Instance#

interface Instance

export async function instanceExample(client) {
    const resolved = await client.instance.resolve({ timeoutMs: 10_000 })
    if (resolved.isErr())
        return resolved
    const channel = resolved.value.links.channel({ id: "1750000000000000000" })
    return { api: resolved.value.endpoints.apiPublic, channel }
}

import type { Client } from "@neontechspace/fluxerly"
export async function instanceExample(client: Client) {
    const resolved = await client.instance.resolve({ timeoutMs: 10_000 })
    if (resolved.isErr()) return resolved
    const channel = resolved.value.links.channel({ id: "1750000000000000000" })
    return { api: resolved.value.endpoints.apiPublic, channel }
}

resolve(options?: RequestOptions): ResultAsync<
    ResolvedInstance,
    InstanceResolveError | CancelledError
>resolve(
  options?: RequestOptions
): ResultAsync<
  ResolvedInstance,
  | InstanceResolveError
  | CancelledError
>

InstanceDomainMigration#

interface InstanceDomainMigration

anonymousRolloutBasisPoints#

Share of signed-out web visitors moved to the new domain, in basis points from 0 through 10,000, or null when not supplied

number | null

enabled#

Whether the instance switched the migration on

boolean

standaloneForwarding#

Whether standalone app installs are forwarded to the new domain, or null when not supplied

boolean | null

InstanceEndpoints#

interface InstanceEndpoints

apiPublic#

Public HTTP API base

The SDK appends its documented /v1 route once, preserving any advertised prefix

string

gateway#

Gateway WebSocket base

The SDK adds its required protocol query without deriving another host

string

invite#

Invite base for instance-specific invite and vanity URLs

string

media#

Public media base for instance-specific generated asset URLs

string

staticCdn#

Static CDN base for instance-specific generated default-asset URLs

string

webapp#

Web application base for instance-specific generated navigation and installation links

string

Presence#

interface Presence

set(input: PresenceInput): Result<void, PresenceFailure>set(
  input: PresenceInput
): Result<void, PresenceFailure>

import { MemberMentionPreferences } from "@neontechspace/fluxerly"
export async function botProfileExample(client, guildId) {
    const presence = client.presence.set({ status: "online", customStatus: { text: "Ready", emoji: { name: "🌱" } } })
    if (presence.isErr())
        return presence
    return client.members.editSelf(guildId, { nickname: "Support", mentionFlags: MemberMentionPreferences.PreferNoMention })
}

import { MemberMentionPreferences, type Client } from "@neontechspace/fluxerly"
export async function botProfileExample(client: Client, guildId: string) {
    const presence = client.presence.set({ status: "online", customStatus: { text: "Ready", emoji: { name: "🌱" } } })
    if (presence.isErr()) return presence
    return client.members.editSelf(guildId, { nickname: "Support", mentionFlags: MemberMentionPreferences.PreferNoMention })
}

setMembers(
    guildId: string,
    memberIds: readonly string[]
): Result<void, PresenceFailure>setMembers(
  guildId: string,
  memberIds: readonly string[]
): Result<void, PresenceFailure>

export function watchSelectedMember(client, guildId, memberId) {
    const subscription = client.on("presenceUpdate", (presence) => {
        if (presence.guildId === guildId && presence.userId === memberId)
            void presence.status
    })
    const selected = client.presence.setMembers(guildId, [memberId])
    if (selected.isErr())
        subscription.close()
    return selected.map(() => subscription)
}

import type { Client } from "@neontechspace/fluxerly"
export function watchSelectedMember(client: Client, guildId: string, memberId: string) {
    const subscription = client.on("presenceUpdate", (presence) => {
        if (presence.guildId === guildId && presence.userId === memberId) void presence.status
    })
    const selected = client.presence.setMembers(guildId, [memberId])
    if (selected.isErr()) subscription.close()
    return selected.map(() => subscription)
}

PresenceInput#

interface PresenceInput

customStatus optional#

New custom status, null to clear it, or omission to retain the latest custom-status request made by this client

CustomStatusInput | null

status#

Visible status to publish on the bot's live gateway connections

PresenceStatus

ResolvedInstance#

interface ResolvedInstance

apiCodeVersion#

Provider code-version indicator from discovery

It is not an API path version

number

assets#

Pure asset URL helpers bound to this instance's media and static-CDN bases

They follow the assets namespace's input-field and fallback rules, return URLs directly and throw AssetUrlError for invalid input

AssetHelpers

discoveryEnabled#

Whether this instance has community directory discovery switched on

True when discovery omits the flag, as Fluxer documents. A present value that is not a boolean makes the discovery document invalid. When false, the discovery namespace's search, apply, edit and withdraw operations fail with reason rejected, HTTP 400 and details.providerCode DISCOVERY_DISABLED, while fetchStatus and fetchCategories still answer. The value is a snapshot from when the client resolved the instance, so an operator's later change appears only in a new client

boolean

domainMigration#

The web domain migration that discovery announced, or null when the instance announced none

Links and OAuth URLs always use the discovered web application base in endpoints, so they follow a migrated domain

InstanceDomainMigration | null

endpoints#

Exact validated service bases from discovery

InstanceEndpoints

links#

Pure application-link helpers bound to this instance's web application base

They return URLs directly, throw HelperError for invalid input and perform no navigation or access check

LinkHelpers

presignedAttachmentUploads#

Whether this instance advertises temporary upload URLs for attachment transfers

boolean

RestRequest#

interface RestRequest extends OperationOptionsinterface RestRequest
  extends OperationOptions

export async function currentUserName(client) {
    const result = await client.rest.request({ method: "GET", path: "/users/@me" })
    return result.isOk() ? result.value.body.username : undefined
}

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
}

auditReason optional#

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

string

body optional#

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

unknown

files optional#

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 AttachmentInput[]

method#

HTTP method

Only POST, PUT, PATCH and DELETE may carry a body or files

"GET" | "POST" | "PUT" | "PATCH" | "DELETE"| "GET" | "POST" | "PUT" | "PATCH"
| "DELETE"

path#

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

string

query optional#

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<Record<string, string | number | boolean | undefined>>Readonly<
  Record<
    string,
    | string | number | boolean
    | undefined
  >
>

timeoutMs optional#

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

number

Inherited from OperationOptions: signal

RestRequests#

interface RestRequests

request<T = unknown>(input: RestRequest): ResultAsync<
    RestResponse<T>,
    ConfigurationError | RestRequestFailure | CancelledError
>request<T = unknown>(
  input: RestRequest
): ResultAsync<
  RestResponse<T>,
  | ConfigurationError
  | RestRequestFailure
  | CancelledError
>

RestResponse#

interface RestResponse<T = unknown>

body#

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

T

headers#

Response headers with lower-case names

Repeated headers are joined with a comma and space as fetch does

Readonly<Record<string, string>>

status#

HTTP status from 200 through 299

number

ScheduleOptions#

interface ScheduleOptions

delayMs optional#

Milliseconds before the first run, an integer from 0 through 2,147,483,647

A repeating task waits intervalMs by default, like an interval timer, and a task that runs once waits 0

number

intervalMs optional#

Repeat the task, waiting this many milliseconds after each run ends before the next one starts, an integer from 1 through 2,147,483,647

Runs therefore never overlap. Without it the task runs once

number

ScheduledTask#

interface ScheduledTask

close(): void

ShutdownOptions#

interface ShutdownOptions

drainMs optional#

Milliseconds to let running work finish before shutdown cancels it, an integer from 0 through 2,147,483,647

The default 0 cancels running handlers at once. The runBot function drains for 5,000 ms by default when asked to stop

number

During the drain the client accepts no new events. New subscriptions and event waits start closed, as after shutdown. Running handlers and commands continue, events already waiting in on handler queues still run, and REST requests continue, including new ones that handlers send. Scheduled task runs in progress continue, while tasks start no new run and new tasks are refused. The connection state stays as it was until the drain ends. The drain ends as soon as no handler or scheduled task is running, no event is waiting and no REST request is in progress, logging lifecycle.drained, or when the time runs out. Then shutdown continues as usual and cancels what is left, logging how many handlers, events, tasks and requests it cut off as a lifecycle.drainTimedOut Warn record. Collectors and subscribe subscriptions receive no events during the drain and end with the shutdown. A shutdown call while another is in progress shares that shutdown and its drain.

A default API handler or scheduled task that awaits a draining shutdown of its own client keeps the drain waiting until the time runs out, so start the shutdown without awaiting it there. A native handler, collector callback or scheduled task that calls shutdown ends at once, and the drain continues for the other work. An invalid value throws ConfigurationError in the default API and dies with it in the Effect API, before shutdown starts

StateObserver#

interface StateObserver

[dispose](): void

close(): void

BotEventContext#

type BotEventContext<
    K extends EventName,
    M extends MessageCore = Message
> =
    & {
          readonly client: Client<M>
          readonly context: EventContext<K, M>
          readonly event: EventMap<M>[K]
          readonly signal: AbortSignal
      }
    & (K extends "messageCreate"
          ? {
                readonly message: M
                readonly reply: (
                    input: ReplyInput | string,
                    options?: Omit<RequestOptions, "signal">
                ) => ReturnType<Client<M>["messages"]["reply"]>
            }
          : { … })type BotEventContext<
  K extends EventName,
  M extends MessageCore = Message
> =
  & {
      readonly client: Client<M>
      readonly context:
        EventContext<K, M>
      readonly event:
        EventMap<M>[K]
      readonly signal: AbortSignal
    }
  & (K extends "messageCreate"
      ? {
          readonly message: M
          readonly reply: (
            input:
              | ReplyInput
              | string,
            options?: Omit<
              RequestOptions,
              "signal"
            >
          ) => ReturnType<
            Client<M>["messages"][
              "reply"
            ]
          >
        }
      : { … })

BotEventHandler#

type BotEventHandler<
    K extends EventName,
    M extends MessageCore = Message
> = (context: BotEventContext<K, M>) => unknowntype BotEventHandler<
  K extends EventName,
  M extends MessageCore = Message
> = (
  context: BotEventContext<K, M>
) => unknown

BotEvents#

type BotEvents<M extends MessageCore = Message> = {
    readonly [K in EventName]?:
        BotEventHandler<K, M> | BotEventOptions<K, M>
}type BotEvents<
  M extends MessageCore = Message
> = {
  readonly [K in EventName]?:
    | BotEventHandler<K, M>
    | BotEventOptions<K, M>
}

ConnectionState#

type ConnectionState =
    | "Disconnected" | "Connecting" | "Connected" | "Recovering"
    | "Closing" | "Closed"type ConnectionState =
    | "Disconnected" | "Connecting"
    | "Connected" | "Recovering"
    | "Closing" | "Closed"

CustomStatusEmoji#

type CustomStatusEmoji =
    { readonly id: string } | { readonly name: string }type CustomStatusEmoji =
    | { readonly id: string }
    | { readonly name: string }

PresenceStatus#

type PresenceStatus = "online" | "idle" | "dnd" | "invisible"type PresenceStatus =
    | "online" | "idle" | "dnd"
    | "invisible"