@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/metrics.ts

@@ -0,0 +1,55 @@
+/**
+ * Effect metrics for REST duration, rate-limit waits, reconnects, drops and handler failures.
+ * Invariant: Updates are synchronous and cheap, and without an exporter they only update the in-memory registry. The
+ * observe client option receives matching measurements in both APIs through the observer module.
+ * Implements [SDK contracts: Logging](/docs/SDK-CONTRACTS.md#logging)
+ */
+import * as Context from "effect/Context"
+import * as Metric from "effect/Metric"
+
+const durationBoundaries = [5, 10, 25, 50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000, 60_000]
+
+const restDuration = Metric.histogram("fluxerly_rest_duration_ms", {
+    description: "Duration of completed REST requests in milliseconds, by route template and HTTP status",
+    boundaries: durationBoundaries,
+})
+const rateLimitWait = Metric.histogram("fluxerly_ratelimit_wait_ms", {
+    description: "Time REST requests waited for rate limits in milliseconds",
+    boundaries: durationBoundaries,
+})
+const reconnects = Metric.counter("fluxerly_gateway_reconnects_total", {
+    description: "Gateway reconnection attempts after an established connection was lost",
+    incremental: true,
+})
+const eventsDropped = Metric.counter("fluxerly_events_dropped_total", {
+    description: "Events not delivered to a subscription, by reason",
+    incremental: true,
+})
+const handlerFailures = Metric.counter("fluxerly_handler_failures_total", {
+    description: "Event and command callbacks that threw or rejected, by event",
+    incremental: true,
+})
+
+const empty = Context.empty() as Context.Context<never>
+
+/** Metric updates are synchronous and cheap. Without an exporter they only update the in-memory registry */
+export const metrics = {
+    rest(route: string, status: number | null, durationMs: number, context: Context.Context<never> = empty) {
+        Metric.withAttributes(restDuration, { route, status: status === null ? "none" : String(status) }).updateUnsafe(
+            durationMs,
+            context,
+        )
+    },
+    rateLimitWait(durationMs: number, context: Context.Context<never> = empty) {
+        rateLimitWait.updateUnsafe(durationMs, context)
+    },
+    reconnect(context: Context.Context<never> = empty) {
+        reconnects.updateUnsafe(1, context)
+    },
+    dropped(reason: string, amount: number, context: Context.Context<never> = empty) {
+        Metric.withAttributes(eventsDropped, { reason }).updateUnsafe(amount, context)
+    },
+    handlerFailure(event: string, context: Context.Context<never> = empty) {
+        Metric.withAttributes(handlerFailures, { event }).updateUnsafe(1, context)
+    },
+}

package/src/internal/moderation.ts

@@ -0,0 +1,288 @@
+/**
+ * Moderation operations: Timeouts, kicks, bans and ban pages.
+ * Invariant: A dispatched moderation request invalidates its guarded resources, not only an uncertain one.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type {
+    BanInput,
+    GuildBan,
+    GuildMember,
+    MemberReference,
+    ModerationOptions,
+    TimeoutOptions,
+    VoiceConnectionReference,
+} from "#sdk/guilds"
+import { identifier, integerInRange as integer, record } from "./decode/primitives.js"
+import { decodeMember, memberFetch, type GuildRequest } from "./guilds.js"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { timestamp } from "./decode/timestamp.js"
+import { normalizedText as text } from "./field-text.js"
+import { auditSettings as validateAuditSettings } from "./audit.js"
+
+export function auditSettings(
+    options?: ModerationOptions,
+): { readonly moderation: true; readonly auditReason?: string } | InputValidationFailure {
+    const settings = validateAuditSettings(options)
+    return settings instanceof InputValidationFailure ? settings : { moderation: true as const, ...settings }
+}
+
+function timeoutSettings(
+    options?: TimeoutOptions,
+): { readonly moderation: true; readonly auditReason?: string } | InputValidationFailure {
+    const settings = auditSettings(options)
+    if (settings instanceof InputValidationFailure) return settings
+    const reason = options?.timeoutReason
+    if (reason !== undefined && reason !== null && !text(reason, 1, 512))
+        return inputValidationFailure(
+            "options.timeoutReason",
+            "length",
+            "Timeout reason must contain 1 through 512 UTF-16 code units after Fluxer's normalization",
+        )
+    return settings
+}
+
+export function memberTimeout(
+    target: MemberReference,
+    durationMs: number | null,
+    options?: TimeoutOptions,
+    clear = false,
+): GuildRequest<GuildMember> | InputValidationFailure {
+    const request = memberFetch(target)
+    const extra = timeoutSettings(options)
+    if (request instanceof InputValidationFailure) return request
+    if (extra instanceof InputValidationFailure) return extra
+    if (!clear && !integer(durationMs, 1, 31_536_000_000))
+        return inputValidationFailure(
+            "durationMs",
+            "range",
+            "Timeout duration must be an integer from 1 through 31,536,000,000 ms (365 days)",
+        )
+    const { guildId, userId } = target
+    return {
+        ...request,
+        ...extra,
+        timeoutReason: true,
+        method: "PATCH",
+        json: JSON.stringify({
+            communication_disabled_until: clear ? null : new Date(Date.now() + durationMs!).toISOString(),
+            ...(options?.timeoutReason === undefined ? {} : { timeout_reason: options.timeoutReason }),
+        }),
+        cache: { selection: { kind: "members", guildId, id: userId }, mutation: true },
+        decode: (value) => {
+            const member = decodeMember(value, guildId)
+            return member?.userId === userId && member.communicationDisabledUntil !== undefined ? member : undefined
+        },
+    }
+}
+
+export function memberKick(
+    target: MemberReference,
+    options?: ModerationOptions,
+): GuildRequest<void> | InputValidationFailure {
+    const request = memberFetch(target)
+    const extra = auditSettings(options)
+    if (request instanceof InputValidationFailure) return request
+    if (extra instanceof InputValidationFailure) return extra
+    return {
+        ...request,
+        ...extra,
+        method: "DELETE",
+        status: 204,
+        decode: () => undefined,
+        cache: { selection: { kind: "members", guildId: target.guildId, id: target.userId }, mutation: true },
+    }
+}
+
+function voiceConnectionId(target: VoiceConnectionReference): string | undefined | InputValidationFailure {
+    const connectionId = target.connectionId
+    if (connectionId === undefined) return undefined
+    if (!text(connectionId, 1, 32))
+        return inputValidationFailure(
+            "target.connectionId",
+            "length",
+            "Voice connection IDs must contain 1 through 32 UTF-16 code units after Fluxer's normalization",
+        )
+    return connectionId
+}
+
+export function memberVoiceMove(
+    target: VoiceConnectionReference,
+    channelId: string | null,
+    options?: ModerationOptions,
+): GuildRequest<GuildMember> | InputValidationFailure {
+    const request = memberFetch(target)
+    const extra = auditSettings(options)
+    if (request instanceof InputValidationFailure) return request
+    if (extra instanceof InputValidationFailure) return extra
+    if (channelId !== null && (!identifier(channelId) || channelId === "0"))
+        return inputValidationFailure(
+            "channelId",
+            "format",
+            "Voice channel IDs must be positive decimal strings or null",
+        )
+    const connectionId = voiceConnectionId(target)
+    if (connectionId instanceof InputValidationFailure) return connectionId
+    return {
+        ...request,
+        ...extra,
+        bucket: "guild:member:voice:update",
+        method: "PATCH",
+        json: JSON.stringify({
+            channel_id: channelId,
+            ...(connectionId === undefined ? {} : { connection_id: connectionId }),
+        }),
+        cache: { ...request.cache!, mutation: true },
+    }
+}
+
+export function memberVoiceFlag(
+    target: MemberReference,
+    field: "mute" | "deaf",
+    input: unknown,
+    options?: ModerationOptions,
+): GuildRequest<GuildMember> | InputValidationFailure {
+    const request = memberFetch(target)
+    const extra = auditSettings(options)
+    if (request instanceof InputValidationFailure) return request
+    if (extra instanceof InputValidationFailure) return extra
+    const key = field === "mute" ? "muted" : "deafened"
+    if (!record(input)) return inputValidationFailure("input", "type", "Voice flag input must be an object")
+    const unsupported = unsupportedKeyFailure(input, [key], "input", "the voice flag input")
+    if (unsupported) return unsupported
+    const enabled = input[key]
+    if (typeof enabled !== "boolean")
+        return inputValidationFailure(`input.${key}`, "type", "Voice flags must be boolean")
+    const decode = request.decode
+    return {
+        ...request,
+        ...extra,
+        bucket: "guild:member:voice:update",
+        method: "PATCH",
+        json: JSON.stringify({ [field]: enabled }),
+        cache: { ...request.cache!, mutation: true },
+        decode: (value) => {
+            const member = decode(value)
+            if (!member) return undefined
+            return field === "mute"
+                ? member.isMuted === undefined
+                    ? undefined
+                    : member
+                : member.isDeafened === undefined
+                  ? undefined
+                  : member
+        },
+    }
+}
+
+/** Whole seconds for a millisecond count that is a multiple of 1,000, otherwise a value every range check rejects */
+function wholeSeconds(milliseconds: unknown): unknown {
+    return typeof milliseconds === "number" && Number.isSafeInteger(milliseconds) && milliseconds % 1_000 === 0
+        ? milliseconds / 1_000
+        : Number.NaN
+}
+
+export function guildBan(
+    target: MemberReference,
+    input?: BanInput,
+    options?: ModerationOptions,
+): GuildRequest<void> | InputValidationFailure {
+    const request = memberKick(target, options)
+    const value = input === undefined ? {} : input
+    if (request instanceof InputValidationFailure) return request
+    if (!record(value)) return inputValidationFailure("input", "type", "Ban input must be an object")
+    const unsupported = unsupportedKeyFailure(
+        value,
+        ["reason", "durationMs", "deleteMessagesMs"],
+        "input",
+        "the ban input",
+    )
+    if (unsupported) return unsupported
+    // Callers supply milliseconds, like timeouts, command cooldowns and the duration command argument, and Fluxer
+    // takes whole seconds
+    const duration = wholeSeconds(value.durationMs === undefined ? 0 : value.durationMs)
+    const removal = wholeSeconds(value.deleteMessagesMs === undefined ? 0 : value.deleteMessagesMs)
+    if (duration !== 0 && !integer(duration, 60, 63_072_000))
+        return inputValidationFailure(
+            "input.durationMs",
+            "range",
+            "Ban duration must be 0 (permanent) or 60,000 through 63,072,000,000 ms (1 minute through 2 years), in whole seconds",
+        )
+    if (!integer(removal, 0, 604_800))
+        return inputValidationFailure(
+            "input.deleteMessagesMs",
+            "range",
+            "Ban message deletion window must be 0 through 604,800,000 ms (7 days), in whole seconds",
+        )
+    if (value.reason !== undefined && !text(value.reason, 0, 512))
+        return inputValidationFailure(
+            "input.reason",
+            "range",
+            "Ban reason must be a string of at most 512 UTF-16 code units after Fluxer's normalization",
+        )
+    return {
+        ...request,
+        method: "PUT",
+        bucket: "guild:bans",
+        path: `/guilds/${target.guildId}/bans/${target.userId}`,
+        json: JSON.stringify({
+            ban_duration_seconds: duration,
+            delete_message_seconds: removal,
+            ...(value.reason === undefined ? {} : { reason: value.reason }),
+        }),
+        ...(removal === 0 ? {} : { deleteAuthorId: target.userId }),
+    }
+}
+
+export function guildUnban(
+    target: MemberReference,
+    options?: ModerationOptions,
+): GuildRequest<void> | InputValidationFailure {
+    const request = memberKick(target, options)
+    if (request instanceof InputValidationFailure) return request
+    return { ...request, bucket: "guild:bans", path: `/guilds/${target.guildId}/bans/${target.userId}` }
+}
+
+export function guildBans(guildId: string): GuildRequest<readonly GuildBan[]> | InputValidationFailure {
+    if (!identifier(guildId)) return inputValidationFailure("guildId", "format", "Guild IDs must be decimal strings")
+    return {
+        guildId,
+        bucket: "guild:bans",
+        path: `/guilds/${guildId}/bans`,
+        method: "GET",
+        status: 200,
+        decode: (value) => {
+            if (!Array.isArray(value)) return undefined
+            const ids = new Set<string>()
+            const bans: GuildBan[] = []
+            for (const item of value) {
+                if (
+                    !record(item) ||
+                    !record(item.user) ||
+                    !identifier(item.user.id) ||
+                    ids.has(item.user.id) ||
+                    typeof item.user.username !== "string" ||
+                    (item.user.bot !== undefined && typeof item.user.bot !== "boolean") ||
+                    !identifier(item.moderator_id) ||
+                    !timestamp(item.banned_at) ||
+                    (item.expires_at !== undefined && item.expires_at !== null && !timestamp(item.expires_at)) ||
+                    (item.reason !== undefined && item.reason !== null && typeof item.reason !== "string")
+                )
+                    return undefined
+                ids.add(item.user.id)
+                bans.push(
+                    Object.freeze({
+                        guildId,
+                        userId: item.user.id,
+                        username: item.user.username,
+                        isBot: item.user.bot === true,
+                        moderatorId: item.moderator_id,
+                        bannedAt: item.banned_at,
+                        ...(item.reason === undefined ? {} : { reason: item.reason as string | null }),
+                        ...(item.expires_at === undefined ? {} : { expiresAt: item.expires_at as string | null }),
+                    }),
+                )
+            }
+            return Object.freeze(bans)
+        },
+    }
+}

package/src/internal/multipart.ts

@@ -0,0 +1,171 @@
+/**
+ * Multipart framing for inline attachment uploads.
+ * Invariant: The body streams on demand without concatenating file bytes or adding an SDK file copy, and declares its exact length.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { randomUUID } from "node:crypto"
+import type { EncodedBody, FilePart } from "./attachments.js"
+import {
+    AttachmentTransferCleanupError,
+    AttachmentTransferSource,
+    AttachmentTransferVerificationCleanupError,
+    type AttachmentTransferBody,
+} from "./transfer-source.js"
+
+const chunkBytes = 65_536
+
+type Segment = { readonly bytes: Uint8Array } | { readonly file: FilePart; readonly source: AttachmentTransferSource }
+
+async function completeCleanup(actions: readonly (() => void | PromiseLike<void>)[]) {
+    const failures: unknown[] = []
+    for (const action of actions) {
+        try {
+            await action()
+        } catch (error) {
+            failures.push(error)
+        }
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, "Attachment multipart cleanup failed")
+}
+
+/** Stream a message multipart body on demand without concatenating file bytes or adding an SDK file copy */
+export function multipart(body: EncodedBody, sources: readonly AttachmentTransferSource[]) {
+    const boundary = `fluxerly-${randomUUID()}`
+    const encoder = new TextEncoder()
+    const segments: Segment[] = [
+        {
+            bytes: encoder.encode(
+                `--${boundary}\r\nContent-Disposition: form-data; name="payload_json"\r\nContent-Type: application/json\r\n\r\n${body.json}\r\n`,
+            ),
+        },
+    ]
+    for (const [fileIndex, file] of body.files.entries()) {
+        const source = sources[fileIndex]
+        if (!source) throw new Error("Attachment multipart source is missing")
+        const filename = file.filename.replaceAll('"', "%22")
+        segments.push(
+            {
+                bytes: encoder.encode(
+                    `--${boundary}\r\nContent-Disposition: form-data; name="files[${file.id}]"; filename="${filename}"\r\nContent-Type: ${file.contentType}\r\n\r\n`,
+                ),
+            },
+            { file, source },
+            { bytes: encoder.encode("\r\n") },
+        )
+    }
+    segments.push({ bytes: encoder.encode(`--${boundary}--\r\n`) })
+    const size = segments.reduce(
+        (sum, segment) => sum + ("bytes" in segment ? segment.bytes.byteLength : segment.file.size),
+        0,
+    )
+    let index = 0
+    let offset = 0
+    let current: AttachmentTransferBody | undefined
+    let currentReader: ReadableStreamDefaultReader<Uint8Array> | undefined
+    let ended = false
+    let controller: ReadableStreamDefaultController<Uint8Array> | undefined
+    const closeCurrent = async (cancel: boolean, cancelReader = cancel) => {
+        const reader = currentReader
+        currentReader = undefined
+        const transfer = current
+        current = undefined
+        await completeCleanup([
+            ...(reader && cancelReader ? [() => reader.cancel()] : []),
+            ...(reader ? [() => reader.releaseLock()] : []),
+            ...(transfer && cancel ? [() => transfer.stop()] : []),
+        ])
+    }
+    const stream = new ReadableStream<Uint8Array>(
+        {
+            async pull(value) {
+                while (index < segments.length) {
+                    const segment = segments[index]!
+                    if ("bytes" in segment) {
+                        if (offset === segment.bytes.byteLength) {
+                            index++
+                            offset = 0
+                            continue
+                        }
+                        const next = Math.min(segment.bytes.byteLength, offset + chunkBytes)
+                        value.enqueue(segment.bytes.subarray(offset, next))
+                        offset = next
+                        return
+                    }
+                    if (!current) {
+                        current = segment.source.open(0, segment.file.size)
+                        currentReader = current.body.getReader()
+                    }
+                    let next: ReadableStreamReadResult<Uint8Array>
+                    try {
+                        next = await currentReader!.read()
+                    } catch (error) {
+                        try {
+                            await closeCurrent(true, false)
+                        } catch (cleanup) {
+                            throw new AttachmentTransferVerificationCleanupError(error, cleanup)
+                        }
+                        throw error
+                    }
+                    if (!next.done) {
+                        value.enqueue(next.value)
+                        return
+                    }
+                    try {
+                        await current.verify()
+                    } catch (error) {
+                        try {
+                            await closeCurrent(true)
+                        } catch (cleanup) {
+                            throw new AttachmentTransferVerificationCleanupError(error, cleanup)
+                        }
+                        throw error
+                    }
+                    try {
+                        currentReader!.releaseLock()
+                        currentReader = undefined
+                        await current.finish()
+                    } catch (error) {
+                        try {
+                            await closeCurrent(true)
+                        } catch (cleanup) {
+                            throw new AttachmentTransferCleanupError(
+                                new AggregateError([error, cleanup], "Attachment multipart finalization failed"),
+                            )
+                        }
+                        if (error instanceof AttachmentTransferCleanupError) throw error
+                        throw new AttachmentTransferCleanupError(error)
+                    }
+                    current = undefined
+                    index++
+                }
+                ended = true
+                value.close()
+            },
+            async cancel() {
+                ended = true
+                await completeCleanup([() => closeCurrent(true), ...sources.map((source) => () => source.close())])
+            },
+            start(value) {
+                controller = value
+            },
+        },
+        { highWaterMark: 0 },
+    )
+    return {
+        body: stream,
+        size,
+        contentType: `multipart/form-data; boundary=${boundary}`,
+        async stop() {
+            const unfinished = !ended
+            if (!ended) {
+                ended = true
+                controller?.error(new Error("Multipart body closed"))
+            }
+            await completeCleanup([
+                () => closeCurrent(unfinished),
+                ...(unfinished ? sources.map((source) => () => source.close()) : []),
+            ])
+        },
+    }
+}

package/src/internal/node-version.ts

@@ -0,0 +1,22 @@
+/**
+ * The Node.js version check each public entry point runs when it loads.
+ * Invariant: Each entry point imports this module first, so an older Node.js stops with this error before other SDK code
+ * runs. A runtime that reports no Node.js version is not checked
+ */
+
+/** Oldest supported Node.js release, matching the package's engines field */
+const minimum = { major: 24, minor: 15 } as const
+
+/** Throw when the reported Node.js version is older than the supported minimum */
+export function checkNodeVersion(versions: { readonly node?: string | undefined } | undefined): void {
+    const found = versions?.node
+    if (typeof found !== "string") return
+    const [major = Number.NaN, minor = Number.NaN] = found.split(".").map(Number)
+    if (!Number.isInteger(major) || !Number.isInteger(minor)) return
+    if (major > minimum.major || (major === minimum.major && minor >= minimum.minor)) return
+    throw new Error(
+        `Fluxerly needs Node.js ${minimum.major}.${minimum.minor} or newer, but this is Node.js ${found}. Install a current Node.js release from https://nodejs.org, then run the bot again`,
+    )
+}
+
+checkNodeVersion(globalThis.process?.versions)