@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/invites.ts

@@ -0,0 +1,87 @@
+/** Set how long an invite lasts, how many times it can be used and whether Fluxer may reuse an existing code.
+ * Creating an invite does not join the recipient or create the destination. Omission requests a new code with
+ * unlimited uses that expires after one day. Fluxer enforces destination access, invite permissions and capacity
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * export function inviteExample(client: Client, channelId: string) {
+ *     return client.invites.create(channelId)
+ * }
+ * export function shareInviteExample(invite: import("@neontechspace/fluxerly").Invite) {
+ *     return { content: invite.url }
+ * }
+ * ```
+ *
+ * @category Invites and webhooks
+ */
+export interface InviteCreate {
+    /** Lifetime in seconds, integer 0–604800. Default 86400. Zero requests no expiry */
+    readonly maxAgeSeconds?: number
+    /** Maximum uses, integer 0–100. Default zero means unlimited uses until expiry */
+    readonly maxUses?: number
+    /** Default true requests a new code. False permits Fluxer to reuse a matching existing invite */
+    readonly unique?: boolean
+    /** Default false. True requests temporary community membership, which Fluxer can remove after disconnect */
+    readonly temporary?: boolean
+}
+
+/** An invite link and the destination details Fluxer returned to this caller.
+ * These returned details are frozen (read-only). Fetching them does not accept the invite or change membership, and the SDK does not keep them.
+ * Codes can grant access to the destination and should only be shared with intended recipients.
+ * The reported counts and expiry do not guarantee that someone can join later
+ *
+ * @category Invites and webhooks
+ */
+export interface Invite {
+    /** Provider code, not a full URL. The SDK never includes it in errors or diagnostics */
+    readonly code: string
+    /** Hosted Fluxer invite URL with an encoded code, ready to share with intended recipients.
+     * Does not check expiry or joinability. Not a credential-safe value for diagnostics or public logs
+     */
+    readonly url: string
+    /** Community invite or invitation to an existing group DM */
+    readonly type: "guild" | "group"
+    /** Minimal destination channel identity, not a full channel snapshot */
+    readonly channel: {
+        /** Decimal destination channel ID, not the invitation code */
+        readonly id: string
+        /** Destination channel name. Null means no name, omission means Fluxer did not supply it */
+        readonly name?: string | null
+        /** Numeric Fluxer channel type. This can describe a community channel or a private group conversation */
+        readonly type: number
+    }
+    /** Present for community invites only. Not a full guild snapshot */
+    readonly guild?: {
+        /** Decimal ID of the community this invitation leads to */
+        readonly id: string
+        /** Community name returned with this invitation */
+        readonly name: string
+    }
+    /** Creator ID. Null means no creator, omission means unavailable */
+    readonly inviterId?: string | null
+    /** Observed destination member count */
+    readonly memberCount: number
+    /** Observed presence count, available for community invites */
+    readonly presenceCount?: number
+    /** ISO 8601 expiry. Null means no expiry, omission means unavailable */
+    readonly expiresAt?: string | null
+    /** Whether Fluxer treats membership gained through this invite as temporary */
+    readonly temporary: boolean
+}
+
+/** Invite details returned by creation and management lists, including creation time and use limits.
+ * Use these observations to inspect or reconcile created codes, not to predict whether a future join succeeds.
+ * The SDK does not cache invite codes or track later uses
+ *
+ * @category Invites and webhooks
+ */
+export interface InviteMetadata extends Invite {
+    /** ISO 8601 creation time */
+    readonly createdAt: string
+    /** Observed uses, which may change immediately */
+    readonly uses: number
+    /** Zero means unlimited uses until expiry */
+    readonly maxUses: number
+    /** Configured lifetime in seconds. Zero means no expiry. Fluxer omits this for group invites */
+    readonly maxAgeSeconds?: number
+}

package/src/logging.ts

@@ -0,0 +1,247 @@
+/**
+ * Severity of an SDK log record, from most to least verbose
+ *
+ * @category Logging and diagnostics
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"
+
+/**
+ * A minimum severity for SDK log output, or silent to emit nothing
+ *
+ * @category Logging and diagnostics
+ */
+export type LogThreshold = LogLevel | "silent"
+
+/** The SDK area that produced a log record. Use it with categories and debug to adjust output for one area.
+ * The lifecycle category covers startup, readiness, connection loss and shutdown, gateway covers protocol traffic,
+ * rest covers HTTP requests and retries, ratelimit covers rate-limit waits, and cache covers cache policy and expiry.
+ * The events category covers subscriptions, handlers and dropped events, commands covers prefix commands,
+ * collectors covers message and reaction collectors, supervisor covers child processes, and sdk covers the logger itself
+ *
+ * @category Logging and diagnostics
+ */
+export type LogCategory =
+    | "lifecycle"
+    | "gateway"
+    | "rest"
+    | "ratelimit"
+    | "cache"
+    | "events"
+    | "commands"
+    | "collectors"
+    | "supervisor"
+    | "sdk"
+
+/** Readable facts about an error attached to a log record or failure report.
+ * Application errors keep their name, string code, message, stack and cause chain with credentials masked.
+ * SDK errors add their fixed code and hint
+ *
+ * @category Logging and diagnostics
+ */
+export interface ErrorInfo {
+    /** Where the failure came from. The value application marks values thrown by application callbacks, provider marks Fluxer rejections and sdk marks SDK failures */
+    readonly origin: "application" | "sdk" | "provider"
+    /** Error name, such as TypeError or GuildOperationError, or Non-Error value (string) for a thrown value that is not an Error */
+    readonly name: string
+    /** Error message, or a text form of a thrown non-Error value */
+    readonly message: string
+    /** Fixed SDK error code, or a string code property of an application error with credentials masked */
+    readonly code?: string
+    /** Suggested next step from an SDK error */
+    readonly hint?: string
+    /** Stack trace, when the value had one */
+    readonly stack?: string
+    /** The next error in the cause chain, limited to a few levels */
+    readonly cause?: ErrorInfo
+    /** Safe structured facts from an SDK error */
+    readonly details?: Readonly<Record<string, unknown>>
+}
+
+/** One structured SDK log record, delivered frozen to sinks and printed by the built-in console output.
+ * Records never contain tokens, Authorization headers, client secrets, invite codes or the user information of a URL,
+ * such as user:password in https://user:password@host/path.
+ * Message payload bodies appear only in explicit unsafe payload mode
+ *
+ * @category Logging and diagnostics
+ */
+export interface LogRecord {
+    /** ISO 8601 wall-clock time when the SDK created the record */
+    readonly time: string
+    /** Record severity */
+    readonly level: LogLevel
+    /** SDK area that produced the record */
+    readonly category: LogCategory
+    /** Stable dotted identifier, such as lifecycle.ready, ratelimit.wait or events.dropped. Match on this rather than message */
+    readonly code: string
+    /** Readable sentence describing what happened, which can change between releases */
+    readonly message: string
+    /** Local shard that the record concerns */
+    readonly shardId?: number
+    /** REST route template with IDs replaced by placeholders, such as /channels/:id/messages */
+    readonly route?: string
+    /** Event name that the record concerns, such as messageCreate */
+    readonly event?: string
+    /** Prefix command name that the record concerns */
+    readonly command?: string
+    /** Identifier of the event subscription or cache observer that the record concerns */
+    readonly subscriptionId?: string
+    /** Elapsed milliseconds for the described work */
+    readonly durationMs?: number
+    /** One-based attempt number for retried work */
+    readonly attempt?: number
+    /** Milliseconds until the next attempt or the end of a wait */
+    readonly delayMs?: number
+    /** HTTP status */
+    readonly status?: number
+    /** WebSocket close code */
+    readonly closeCode?: number
+    /** Other safe facts, such as counts, opcodes and dispatch types */
+    readonly fields?: Readonly<Record<string, string | number | boolean | null>>
+    /** The error that the record describes */
+    readonly error?: ErrorInfo
+}
+
+/** A synchronous callback that receives each emitted SDK record.
+ * Return values are ignored and promises are not awaited. A thrown error or rejected promise is counted in
+ * diagnostics().counters.sinkFailures and reported once on standard error, without stopping SDK work or other sinks
+ *
+ * @category Logging and diagnostics
+ */
+export type LogSink = (record: LogRecord) => void
+
+/**
+ * Configure what the SDK logs and where the output goes. Both entry points accept the same settings.
+ * With no settings, the SDK prints Info and higher records, including startup, readiness, connection loss,
+ * rate-limit waits of at least one second, shutdown and full application errors.
+ * The FLUXERLY_DEBUG environment variable, read when the client is created, enables Debug records:
+ * 1, true or * for every category, or a comma-separated list such as gateway,rest. A debug value passed to
+ * client.logging.configure replaces those categories while the client runs.
+ * HTTP 401 and 403 rejections log a rest.rejected Warn even when handled. An unhandled handler failure with that same
+ * rejection, directly or in its cause chain, replaces its Warn if it happens within one second. A later handler failure
+ * also logs its own record, because the Warn has already been emitted.
+ * Logging never changes operation results, and records never contain credentials
+ *
+ * @category Logging and diagnostics
+ */
+export interface LoggingOptions {
+    /** Minimum severity to emit, default info. The value silent emits nothing, including application error reports without
+     * a hook and unsafe payload records
+     */
+    readonly level?: LogThreshold
+    /** Per-category minimum severity that replaces level for that category, such as { rest: "debug", cache: "warn" } */
+    readonly categories?: Readonly<Partial<Record<LogCategory, LogThreshold>>>
+    /** Enable Debug records for every category with true, or for the listed categories.
+     * At creation it adds to FLUXERLY_DEBUG. In client.logging.configure it replaces the current Debug categories,
+     * including those from FLUXERLY_DEBUG, and false or an empty list turns them all off.
+     * It lowers, never raises, the configured threshold
+     */
+    readonly debug?: boolean | readonly LogCategory[]
+    /** Built-in console output format. The value pretty prints readable single lines with indented stacks, and json prints one LogRecord per line.
+     * Info and lower records go to standard output and Warn and higher to standard error, and each stream decides its own default.
+     * The default is pretty when that stream is a terminal and json otherwise.
+     * Without this setting, the FLUXERLY_LOG_FORMAT environment variable, pretty or json, read when the client is created,
+     * chooses the format for both streams, and FLUXERLY_LOG_COLOR forces color on with 1, true, yes or on, and off with
+     * 0, false, no or off, for pretty output. Another nonempty value of either variable is ignored with one
+     * sdk.unknownEnvironmentValue Warn at startup. NO_COLOR still disables color. A supervisor sets both variables for children whose output it forwards.
+     * Native clients without sink or format send records to the Effect logger instead, and the environment variables do not change that
+     */
+    readonly format?: "pretty" | "json"
+    /** Receive records instead of the built-in console output. Pass one function or an array of them.
+     * Each sink is called synchronously in order for every emitted record
+     */
+    readonly sink?: LogSink | readonly LogSink[]
+    /** Collapse repeated identical Warn, Error and Fatal records within a window. Records about different shards or
+     * subscriptions are not identical, so each one's first occurrence is shown.
+     * The next identical record after the window reports how many were suppressed in fields.repeated and as "(repeated N× since last shown)" in its message,
+     * and shutdown reports any remainder the same way. When more than 512 distinct records are tracked, the oldest one's window ends early and its count is reported then.
+     * Default { windowMs: 60000 }. A false value or a windowMs of 0 disables collapsing
+     */
+    readonly dedupe?:
+        | {
+              /** Milliseconds during which identical records are collapsed, default 60,000. 0 disables collapsing */
+              readonly windowMs?: number
+          }
+        | false
+    /** Print received and sent payload bodies at Trace level for debugging, for all categories or the listed ones.
+     * Payload records bypass the level setting, except that a category set to silent prints no payloads.
+     * Payloads can contain private message content, so the SDK prints a Warn banner once, at startup or before the first
+     * payload record, whichever comes first, even when the level would hide Warn records.
+     * Received REST bodies show at most their first 65,536 bytes.
+     * Tokens, Authorization headers, client secrets, passwords, cookies, invite codes and the user information of a URL
+     * stay masked even in this mode, including credential-key values in a truncated JSON response
+     */
+    readonly unsafe?: {
+        /** Must be true to acknowledge that payload bodies can contain private content */
+        readonly payloads: true
+        /** Print payloads only for these categories, such as gateway or rest. Omit for every category */
+        readonly categories?: readonly LogCategory[]
+    }
+}
+
+/**
+ * The level, categories and debug settings of LoggingOptions, which client.logging.configure changes while a client runs
+ *
+ * @category Logging and diagnostics
+ */
+export type LogLevelSettings = Pick<LoggingOptions, "level" | "categories" | "debug">
+
+/**
+ * Running totals for one client since creation, returned by diagnostics().counters. Values only increase
+ *
+ * @category Logging and diagnostics
+ */
+export interface ClientCounters {
+    /** Event handler and command callbacks that threw or rejected */
+    readonly handlerFailures: number
+    /** Failed onError hooks, which threw or rejected while reporting a failure */
+    readonly hookFailures: number
+    /** Failure reports that could not be queued for a busy hook and were logged instead */
+    readonly reportsDropped: number
+    /** Events not delivered to a subscription, by reason. The reason overflow is a full queue, malformed is a rejected dispatch,
+     * collector is a full collector buffer and closed is a shutdown or closed subscription
+     */
+    readonly eventsDropped: {
+        /** Events dropped because a subscription queue was full */
+        readonly overflow: number
+        /** Gateway dispatches skipped because they failed validation */
+        readonly malformed: number
+        /** Messages or reactions dropped because a collector buffer was full */
+        readonly collector: number
+        /** Events still waiting when a subscription or the client closed, plus events a draining shutdown refused after it
+         * stopped accepting new ones
+         */
+        readonly closed: number
+    }
+    /** Cache changes not delivered to a cache.onChange listener because its waiting changes reached maxPendingChanges */
+    readonly cacheChangesDropped: number
+    /** Gateway messages rejected as invalid protocol data, including skipped malformed dispatches */
+    readonly protocolFailures: number
+    /** Dispatch types the SDK does not handle */
+    readonly unknownDispatches: number
+    /** Gateway opcodes the SDK does not handle */
+    readonly unknownOpcodes: number
+    /** Automatic REST request retries */
+    readonly restRetries: number
+    /** REST rate-limit waits that took place. A limit whose wait would pass the request deadline fails the request
+     * without waiting, logs ratelimit.deadline and is not counted here
+     */
+    readonly rateLimitWaits: number
+    /** REST requests that failed with reason busy before sending, because the REST queue or the upload byte budget was
+     * full. The first such failure in a minute also logs rest.busy at Warn
+     */
+    readonly restBusy: number
+    /** Gateway reconnection attempts after an established connection was lost */
+    readonly reconnects: number
+    /** Successful session resumes */
+    readonly resumes: number
+    /** Log output failures: Sink and observe calls that threw or rejected, console or Effect logger output that failed,
+     * and failure reports that could not be formatted. The first one is described on standard error
+     */
+    readonly sinkFailures: number
+    /** Shutdown or subscription cleanup steps that failed */
+    readonly cleanupFailures: number
+    /** Prefix commands rejected by a guard, cooldown or argument parser */
+    readonly commandRejections: number
+    /** Messages with the command prefix that matched no command */
+    readonly unmatchedCommands: number
+}

package/src/member-chunks.ts

@@ -0,0 +1,195 @@
+import { FluxerlyError, operationDetails } from "./errors.js"
+import type { OperationOptions } from "./client.js"
+import type { ClientClosedError } from "./errors.js"
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js"
+import type { PresenceUpdate } from "./events.js"
+import type { GuildMember } from "./guilds.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+
+/** Choose the members to request through one community's gateway shard.
+ * Supply exactly one of all, userIds or query, with an optional presences flag.
+ * The SDK requests a response when the stream is consumed. It does not subscribe to future changes, fetch REST pages or keep a community member list
+ *
+ * @category Guilds and members
+ */
+export type MemberChunkQuery = (
+    | {
+          /** Request Fluxer's full-list mode, capped by the provider at 100,000 members and subject to gateway rate limits */
+          readonly all: true
+          /** Not accepted with all. Choose one selection mode */
+          readonly userIds?: never
+          /** Not accepted with all. Choose one selection mode */
+          readonly query?: never
+          /** Not accepted with all, which uses the provider's full-list cap */
+          readonly limit?: never
+      }
+    | {
+          /** Select 1–100 distinct user IDs as positive decimal strings with no leading zeroes, no greater than 9223372036854775807.
+           * Missing IDs are omitted without an explanation
+           */
+          readonly userIds: readonly string[]
+          /** Not accepted with userIds. Choose one selection mode */
+          readonly all?: never
+          /** Not accepted with userIds. Choose one selection mode */
+          readonly query?: never
+          /** Not accepted with userIds, whose length already bounds the request */
+          readonly limit?: never
+      }
+    | {
+          /** Case-insensitive prefix of nickname, global name or username, at most 4,096 UTF-16 code units and well-formed Unicode.
+           * The complete encoded request must also fit the 4,096-byte gateway payload budget.
+           * Empty selects an initial bounded list, not full-list mode
+           */
+          readonly query: string
+          /** Maximum matching members, integer 1–100, default 25 */
+          readonly limit?: number
+          /** Not accepted with query. Choose one selection mode */
+          readonly all?: never
+          /** Not accepted with query. Choose one selection mode */
+          readonly userIds?: never
+      }
+) & {
+    /** Include available visible presences, default false. Missing presence is not proof of offline status */
+    readonly presences?: boolean
+}
+
+/** One batch yielded by members.iterateChunks, with frozen member observations and optional visible presences.
+ * Batches arrive in Fluxer's order. The SDK does not combine them into a single snapshot or store them in the member cache.
+ * Already yielded batches remain available to the application if a later batch fails
+ *
+ * @category Guilds and members
+ */
+export interface MemberChunk {
+    /** Requested guild ID as a positive decimal string with no leading zeroes, no greater than 9223372036854775807 */
+    readonly guildId: string
+    /** Zero-based batch index, delivered in provider order without gaps or duplicate indices */
+    readonly index: number
+    /** Number of batches advertised for this response, from 1 through 100. It does not prove a complete community roster */
+    readonly count: number
+    /** Up to 1,000 frozen member observations. An empty response is one batch with an empty array */
+    readonly members: readonly GuildMember[]
+    /** Present only when requested, including an empty array when Fluxer supplied no visible presences.
+     * Contains only members in this batch, with the request's guild context. No live subscription is created
+     */
+    readonly presences?: readonly PresenceUpdate[]
+    /** On the final batch of an explicit user-ID request, requested IDs without a returned member, in input order.
+     * Omission does not distinguish missing membership, access restrictions or a provider-side failure
+     */
+    readonly omittedUserIds?: readonly string[]
+}
+
+/** Set how long a member stream can run and how many unread bytes it can hold.
+ * The SDK checks and copies these settings when consumption starts, not when the iterator or native Stream is created.
+ * One client admits one member stream across its local shards, sharing four request slots with count calls.
+ * It sends at most 12 member requests in any 11 seconds, keeping under Fluxer's limit of 12 per account in 10 seconds.
+ * The children of one supervisor keep that count together.
+ * Ending the stream early releases the SDK's local request slot but cannot stop work Fluxer has already started
+ *
+ * @category Guilds and members
+ */
+export interface MemberChunkOptions {
+    /** Total milliseconds from dispatch until the final batch arrives, integer 1–2,147,483,647, default 30,000.
+     * Pausing consumption does not pause this deadline or the provider. No timeout applies after the full response arrives
+     */
+    readonly timeoutMs?: number
+    /** Maximum source-JSON bytes counted for unread batches, a positive safe integer, default 4,194,304 (4 MiB).
+     * Includes a single batch delivered directly to a waiting reader. Overflow fails rather than dropping batches.
+     * This bounds the SDK's batch byte accounting, not total JavaScript heap, decoding overhead or caller-held batches
+     */
+    readonly maxPendingBytes?: number
+}
+
+/**
+ * Stream options for the default API. Abort releases local intake even while consumption is paused, not remote provider work
+ *
+ * @category Guilds and members
+ */
+export interface DefaultMemberChunkOptions extends MemberChunkOptions, OperationOptions {}
+
+/** A member stream stopped before it could return every batch.
+ * The SDK releases local intake and does not automatically resend the request.
+ * Already yielded batches are not undone, but unread batches are discarded when intake fails.
+ * Metadata contains no requested IDs, member data, correlation nonce or provider payload
+ *
+ * @category Errors
+ */
+export class MemberChunkError extends FluxerlyError {
+    /** Stable expected-failure discriminator */
+    readonly _tag = "MemberChunkError"
+    /** Public operation that failed */
+    readonly operation = "members.iterateChunks"
+    /** SDK-owned local input detail, or null for non-input failures */
+    readonly inputValidation: InputValidationDetail | null
+    /** Failure category.
+     * The reason input means invalid selection or settings, and notConnected means the community's shard is absent or not ready.
+     * The reason busy means a member stream is already running, shared request capacity is full, or the shard's internal command queue is full.
+     * The reason response means malformed or out-of-order batches, and overflow means the unread byte budget was exceeded.
+     * The reason timeout means the complete response missed its deadline, and connectionLost means its shard lost the connection.
+     * The reason rateLimit means the request is over a Fluxer member request limit.
+     * Either Fluxer refused a repeated full-list request, or this client already sent 12 member requests in the last 11 seconds and the SDK did not send this one
+     */
+    readonly reason:
+        "input" | "notConnected" | "busy" | "response" | "overflow" | "timeout" | "connectionLost" | "rateLimit"
+    /** Milliseconds to wait before the next member request for rateLimit, otherwise null.
+     * It comes from Fluxer's answer or from the SDK's count of this client's recent requests. The SDK never retries automatically
+     */
+    readonly retryAfterMs: number | null
+
+    /** Describe a member-stream failure. Construction sends no request and does not stop or resend a stream */
+    constructor(options: {
+        /** Failure category, as described on the reason field */
+        readonly reason: MemberChunkError["reason"]
+        /** Milliseconds to wait before the next member request for rateLimit. Defaults to null */
+        readonly retryAfterMs?: number | null | undefined
+        /** Safe local input detail. It never retains rejected values, credentials, or Fluxer data, and names an unsupported key only when it looks like a field name. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        /** Underlying failure retained as the error's cause */
+        readonly cause?: unknown
+    }) {
+        const { reason, retryAfterMs = null, inputValidation = null } = options
+        super(
+            operationErrorMessage({
+                subject: "Member chunk",
+                operation: "request",
+                reason,
+                outcome: reason === "input" ? "notDispatched" : "unknown",
+                // The general rateLimit text says Fluxer refused the request, which is untrue when the SDK withheld it
+                inputExplanation:
+                    inputValidation?.explanation ??
+                    (reason === "rateLimit"
+                        ? "The request is over a Fluxer limit on how often members can be requested"
+                        : null),
+                retryAfterMs,
+                facts: { read: true },
+            }),
+            {
+                code: `memberChunks.${reason}`,
+                hint:
+                    reason === "rateLimit"
+                        ? retryAfterMs === null
+                            ? "Wait before requesting members again"
+                            : `Wait at least ${retryAfterMs} ms before requesting members again`
+                        : operationFailureHint({
+                              reason,
+                              outcome: reason === "input" ? "notDispatched" : "unknown",
+                              retryAfterMs,
+                              read: true,
+                              inputPath: inputValidation?.path ?? null,
+                          }),
+                cause: options.cause,
+                details: operationDetails({ reason, retryAfterMs }),
+            },
+        )
+        this.name = this._tag
+        this.inputValidation = freezeInputValidationDetail(inputValidation)
+        this.reason = reason
+        this.retryAfterMs = retryAfterMs
+    }
+}
+
+/**
+ * Expected stream failure. Native interruption and CancelledError in the default API remain separate
+ *
+ * @category Errors
+ */
+export type MemberChunkFailure = MemberChunkError | ClientClosedError