@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/code-catalogue.d.ts

@@ -0,0 +1,712 @@
+/**
+ * Catalogue of every SDK error code and log record code, the source text of the website's error and log codes page.
+ * Invariant: Every emitted log code is a key of logCodes, which the compiler enforces through LogCode, and the website
+ * generator fails when an error code or error code family in the source has no entry here or an entry names a code
+ * that no longer exists. Entries describe the code in plain words and never quote runtime values
+ */
+import type { LogLevel } from "#sdk/logging";
+/** One catalogue entry: What the code means and, when there is one, what to do about it */
+export interface CodeEntry {
+    /** What happened, in one or two short sentences without a final period */
+    readonly meaning: string;
+    /** The usual fix or next step, without a final period. Absent when the code needs no action */
+    readonly action?: string;
+}
+/** One error code or error code family. A family key such as guild.<reason> lists its values */
+export interface ErrorCodeEntry extends CodeEntry {
+    /** The error class that carries this code */
+    readonly error: string;
+    /** For a family with one placeholder, the values that replace it */
+    readonly values?: readonly string[];
+}
+/** One log record code with the levels it is emitted at */
+export interface LogCodeEntry extends CodeEntry {
+    readonly levels: readonly LogLevel[];
+}
+/**
+ * What each operation reason means, shown once on the page for every family that uses them.
+ * Read by the website generator
+ *
+ * @public
+ */
+export declare const operationReasonMeanings: {
+    readonly input: "An input value is invalid, so nothing was sent to Fluxer. The error's inputValidation.path names it";
+    readonly busy: "Too many requests of this kind were already pending in the client, so nothing was sent";
+    readonly notFound: "Fluxer answered HTTP 404. The resource does not exist or is not visible to this bot";
+    readonly rejected: "Fluxer refused the request. The error's apiError, or details.providerCode for a newer code, says why. For a missing permission, details.requiredPermissions lists the permissions the operation needs when the SDK knows them";
+    readonly network: "A network error interrupted the request";
+    readonly response: "Fluxer's answer did not have the expected format. The failing field or check is in details.responseField";
+    readonly timeout: "The operation did not finish within its timeoutMs";
+    readonly rateLimit: "Fluxer rate-limited the request, and the SDK could not wait and retry it, for example because the wait would pass the timeout";
+};
+/**
+ * Error codes and families, keyed by code. Family keys use a placeholder such as <reason>. Read by the website generator
+ *
+ * @public
+ */
+export declare const errorCodes: {
+    readonly "configuration.invalid": {
+        readonly error: "ConfigurationError";
+        readonly meaning: "An option or setting is invalid, so the requested work did not start. The error's field names the setting";
+        readonly action: "Fix the named setting. The hint suggests the closest supported option for a misspelled key";
+    };
+    readonly "auth.rejected": {
+        readonly error: "AuthenticationError";
+        readonly meaning: "Fluxer rejected the bot token when the client connected, reconnected or counted communities for automatic sharding";
+        readonly action: "Check the whole bot token and the application owner's account standing. A valid token can be rejected if that account is closed or disabled, which a new token cannot fix. The rejection alone does not identify the cause. The SDK does not retry it";
+    };
+    readonly "connection.<phase>.<reason>": {
+        readonly error: "ConnectionError";
+        readonly meaning: "Instance discovery or the gateway connection failed. The phase is discovery or gateway, and the reason is network, protocol or closed. The message explains a known close code and names it";
+        readonly action: "Check network access to the Fluxer instance. Follow the hint for rejected tokens and shard close codes";
+    };
+    readonly "connection.timeout": {
+        readonly error: "ConnectionTimeoutError";
+        readonly meaning: "The connection to Fluxer, or instance discovery, was not ready within its timeout";
+        readonly action: "Check network access, or raise the timeout that expired, usually connection.startupTimeoutMs";
+    };
+    readonly "connection.shard": {
+        readonly error: "ShardConnectionError";
+        readonly meaning: "One shard failed to start or lost its connection for good, so it stopped. The cause is the shard's own failure";
+        readonly action: "Read the cause and its hint";
+    };
+    readonly "ratelimit.connection": {
+        readonly error: "RateLimitError";
+        readonly meaning: "Fluxer rate-limited the gateway connection or a request made while connecting";
+        readonly action: "Wait at least retryAfterMs before connecting again";
+    };
+    readonly "client.busy": {
+        readonly error: "ClientBusyError";
+        readonly meaning: "The client is already connecting or connected, because connect or run was called before";
+        readonly action: "Call connect or run once per client and await that call";
+    };
+    readonly "client.closed": {
+        readonly error: "ClientClosedError";
+        readonly meaning: "The client is shutting down or has shut down, so it cannot do more work";
+        readonly action: "Create a new client to connect again";
+    };
+    readonly "operation.cancelled": {
+        readonly error: "CancelledError";
+        readonly meaning: "A default API operation stopped because its AbortSignal was aborted, for example during shutdown. The details.operation field names the call";
+        readonly action: "No action is needed during shutdown. Otherwise check what aborted the signal";
+    };
+    readonly "application.callbackFailed": {
+        readonly error: "ApplicationError";
+        readonly meaning: "An application callback that the SDK ran, such as runBot setup, threw or rejected. The cause is the original value";
+        readonly action: "Fix the callback named by details.source";
+    };
+    readonly "application.defect": {
+        readonly error: "SdkDefect";
+        readonly meaning: "An application callback or an option getter threw where the SDK could not return a typed failure";
+        readonly action: "Fix the callback or getter that raised the cause";
+    };
+    readonly "sdk.defect": {
+        readonly error: "SdkDefect";
+        readonly meaning: "An unexpected fault inside the SDK or its cleanup";
+        readonly action: "Report it with the output of describeError";
+    };
+    readonly "bot.workerStopped": {
+        readonly error: "CriticalWorkerStoppedError";
+        readonly meaning: 'One of the bot\'s event or command subscriptions ended while the bot was still running, so the bot stopped. The details.workerIndex field numbers it from 0. A subscription set to overflow "stop" whose queue overflowed also names its event and the exceeded capacity in details';
+        readonly action: "Keep the bot's subscriptions open while it runs. The hint explains how subscriptions are numbered, or how to keep up with the events after an overflow";
+    };
+    readonly "events.overflow": {
+        readonly error: "EventOverflowError";
+        readonly meaning: "A subscription's queue exceeded its limit and the overflow policy stopped it";
+        readonly action: "Handle events faster, raise the pending limits or choose a dropping overflow policy";
+    };
+    readonly "events.readBusy": {
+        readonly error: "EventReadBusyError";
+        readonly meaning: "An event read was started while another read on the same subscription was pending";
+        readonly action: "Await the pending next call before calling next again";
+    };
+    readonly "events.wait.<reason>": {
+        readonly error: "EventWaitError";
+        readonly values: readonly ["timeout", "filter"];
+        readonly meaning: "An event wait ended without a match before its deadline, or its filter threw or returned a non-boolean";
+        readonly action: "Raise timeoutMs, or make the filter return true or false synchronously";
+    };
+    readonly "message.send.<reason>": {
+        readonly error: "MessageError";
+        readonly values: readonly ["input", "busy", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: "A message send failed. The reason says why, as listed under operation reasons, and a send reports HTTP 404 as rejected";
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true. A send whose outcome is unknown may already have created the message";
+    };
+    readonly "message.<reason>": {
+        readonly error: "MessageOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: `${string}. Publishing requires an unpublished source message in an announcement channel, excluding replies, system messages, forwarded messages and received crosspost copies. Publishing and editing a published message have separate rate limits`;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true. For publishing preconditions, check the source channel and message. For rate limits, wait at least retryAfterMs before repeating the call";
+    };
+    readonly "guild.<reason>": {
+        readonly error: "GuildOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: string;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "channel.<reason>": {
+        readonly error: "ChannelOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: `${string}. Announcement operations require an announcement source. Following requires a community text destination that does not already follow that source and has compatible content warnings or age restrictions. Only text and announcement channels can convert into each other`;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true. Choose a compatible follow destination. Before converting a text channel to an announcement channel, remove its channel-follower webhooks";
+    };
+    readonly "user.<reason>": {
+        readonly error: "UserOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: string;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "webhook.<reason>": {
+        readonly error: "WebhookOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: `${string}. Moving a channel-follower webhook requires a community text destination that does not already follow its source and has compatible content warnings or age restrictions. Editing a published webhook message can reach the published-message edit rate limit`;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true. Choose a compatible destination for a follower webhook. For a published-message edit rate limit, wait at least retryAfterMs before editing again";
+    };
+    readonly "application.<reason>": {
+        readonly error: "BotApplicationOperationError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: string;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "rest.<reason>": {
+        readonly error: "RestRequestError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: string;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "attachment.<reason>": {
+        readonly error: "AttachmentRefreshError";
+        readonly values: readonly ["input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: string;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "attachment.download.<reason>": {
+        readonly error: "AttachmentDownloadError";
+        readonly values: readonly ["input", "untrustedUrl", "busy", "network", "response", "tooLarge", "timeout"];
+        readonly meaning: "An attachment download failed. The reason untrustedUrl means the URL is not on this instance's media host, and tooLarge means the attachment is larger than maxBytes";
+        readonly action: "Pass attachments received from this client, and raise maxBytes for tooLarge";
+    };
+    readonly "oauth.<reason>": {
+        readonly error: "OAuthOperationError";
+        readonly values: readonly ["input", "busy", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: `${string}. The oauthError field names a standard OAuth error code, such as invalid_grant`;
+        readonly action: "Read the hint, and apiError or details.providerCode for a Fluxer rejection. Repeat the call only when errors.isRetryable returns true";
+    };
+    readonly "cleanup.<reason>": {
+        readonly error: "MessageCleanupError";
+        readonly values: readonly ["filter", "closed", "input", "busy", "notFound", "rejected", "network", "response", "timeout", "rateLimit"];
+        readonly meaning: "A message cleanup stopped. The phase says whether history scanning or deletion failed";
+        readonly action: "Check selectedMessageIds and terminalBatchIds before running the cleanup again";
+    };
+    readonly "count.<reason>": {
+        readonly error: "CountOperationError";
+        readonly values: readonly ["input", "notConnected", "busy", "timeout", "connectionLost", "response"];
+        readonly meaning: "A fresh member or presence count over the gateway failed. The reason notConnected means the community's shard is not ready, and connectionLost means it disconnected before the answer";
+        readonly action: "Connect the client first, and retry after a timeout or lost connection";
+    };
+    readonly "memberChunks.<reason>": {
+        readonly error: "MemberChunkError";
+        readonly values: readonly ["input", "notConnected", "busy", "response", "overflow", "timeout", "connectionLost", "rateLimit"];
+        readonly meaning: "A gateway member request failed before its last chunk arrived. The reason overflow means unread batches passed maxPendingBytes";
+        readonly action: "Connect the client first, read batches promptly, and wait retryAfterMs after rateLimit";
+    };
+    readonly "presence.<reason>": {
+        readonly error: "PresenceError";
+        readonly values: readonly ["input", "limit"];
+        readonly meaning: "A presence update or presence member selection was invalid, or the selection was larger than the SDK's limits (reason limit)";
+        readonly action: "Correct the input named by inputValidation.path, or select fewer members";
+    };
+    readonly "pagination.<reason>": {
+        readonly error: "PaginationError";
+        readonly values: readonly ["input", "cursorStalled", "pageLimit", "indexing"];
+        readonly meaning: "An iterator stopped. The reason cursorStalled means Fluxer repeated a page, and indexing means search results are not ready yet";
+        readonly action: "Retry indexing later, and raise maxPages for pageLimit";
+    };
+    readonly "collector.<reason>": {
+        readonly error: "CollectorError";
+        readonly values: readonly ["notConnected", "connectionLost", "filter", "handler", "overflow"];
+        readonly meaning: "A message or reaction collector failed instead of ending normally";
+        readonly action: "Start collectors after the client is ready, start a new one after a lost connection, fix a failing filter or callback, or raise the limit named in the message";
+    };
+    readonly "gateway.send.<reason>": {
+        readonly error: "GatewaySendError";
+        readonly values: readonly ["input", "reserved", "notOwned", "notReady", "busy"];
+        readonly meaning: "A raw gateway send was invalid, used an opcode the SDK manages, or had no ready shard to use";
+        readonly action: "Send only application opcodes to a shard this client owns after it is ready";
+    };
+    readonly "helper.<reason>": {
+        readonly error: "HelperError";
+        readonly values: readonly ["id", "markup", "time", "permissionBits", "link", "color", "text", "limit", "shardCount"];
+        readonly meaning: "A formatting or parsing helper received a value it cannot use";
+        readonly action: "Pass a value of the documented form";
+    };
+    readonly "asset.<reason>": {
+        readonly error: "AssetUrlError";
+        readonly values: readonly ["target", "id", "hash", "options"];
+        readonly meaning: "An asset URL could not be built from the given object or options";
+        readonly action: "Pass the object received from Fluxer and supported size and format options";
+    };
+    readonly "supervisor.<reason>": {
+        readonly error: "SupervisorError";
+        readonly values: readonly ["closed", "spawn", "protocol", "restartLimit", "startupTimeout", "shardCount"];
+        readonly meaning: "The shard supervisor failed to start or keep its child processes";
+        readonly action: "Read the supervisor log records for the child that failed";
+    };
+    readonly "supervisor.child.<reason>": {
+        readonly error: "SupervisorChildError";
+        readonly values: readonly ["disconnected", "protocol"];
+        readonly meaning: "A supervised child lost its connection to the parent process or received an invalid message";
+        readonly action: "Start the child only through the supervisor";
+    };
+    readonly "testing.unhandledFailures": {
+        readonly error: "UnhandledTestFailuresError";
+        readonly meaning: "A test client logged failures that the test neither handled nor asserted";
+        readonly action: "Fix the failing code, assert the failures before shutdown, or handle them with onError";
+    };
+    readonly "testing.timeout": {
+        readonly error: "TestTimeoutError";
+        readonly meaning: "A test wait did not finish within its timeout";
+        readonly action: "Check that the code under test sends the request, or raise timeoutMs";
+    };
+};
+/** Log record codes, keyed by code */
+export declare const logCodes: {
+    readonly "lifecycle.starting": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "The client started connecting, with its SDK version and shard plan";
+    };
+    readonly "lifecycle.startupDeadline": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "Starting several shards may take longer than connection.startupTimeoutMs, because the SDK starts shard sessions one second apart";
+    };
+    readonly "lifecycle.automaticSharding": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "Automatic sharding counted the bot's communities and chose the shard count from that number";
+    };
+    readonly "lifecycle.resharded": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "Fluxer closed a shard with 4011 (sharding required) on an automatically sized client or a client without sharding settings, so the SDK counted the communities again and moved every shard to a larger automatic plan. Every shard started a new session, so events sent during the move were missed";
+        readonly action: 'No action is needed. If it repeats, the bot may be growing fast, and each move is logged with the new total. A client without sharding settings moves again at each start while the bot has outgrown one shard, which sharding "auto" avoids';
+    };
+    readonly "lifecycle.cacheRefill": {
+        readonly levels: readonly ["info", "warn"];
+        readonly meaning: "Shards resumed sessions from the session store, which carry no community data, so the SDK refilled the enabled community, role and channel caches through REST. Warn means some communities failed or the refill stopped early, such as when the community list repeated a page";
+        readonly action: "At Warn, read the message and any error. The affected cache entries fill as events and requests arrive";
+    };
+    readonly "lifecycle.attempt": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A shard started a connection attempt";
+    };
+    readonly "lifecycle.ready": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "A shard is ready and receives events";
+    };
+    readonly "lifecycle.connected": {
+        readonly levels: readonly ["info", "warn"];
+        readonly meaning: "Every shard of the client is connected, with the bot's name and the number of communities it is in. Warn means the bot is in no community yet";
+        readonly action: "At Warn, invite the bot to a community with the installation link in the message";
+    };
+    readonly "lifecycle.retry": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A shard's connection attempt failed and will be retried after the delay";
+        readonly action: "Check network access if it repeats";
+    };
+    readonly "lifecycle.connectionLost": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "An established shard connection was lost and the SDK is reconnecting";
+        readonly action: "No action is needed unless it repeats";
+    };
+    readonly "lifecycle.connectionEnded": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "A shard stopped for good, for example after a rejected token, an invalid shard setting or an exhausted recovery schedule";
+        readonly action: "Read the error's hint";
+    };
+    readonly "lifecycle.sessionReset": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A shard's session can no longer resume, so the next connection starts a new session and missed events are lost";
+    };
+    readonly "lifecycle.sessionRestored": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "A shard is resuming a session saved by the session store";
+    };
+    readonly "lifecycle.sessionSaved": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A shard's session was saved for a later Resume";
+    };
+    readonly "lifecycle.sessionSaveFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The session store's save function threw, rejected or timed out during shutdown, so the next start begins a new session";
+        readonly action: "Fix the session store's save function";
+    };
+    readonly "lifecycle.sessionLoadFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The session store's load function threw, rejected or timed out, so the shard starts a new session";
+        readonly action: "Fix the session store's load function";
+    };
+    readonly "lifecycle.sessionSnapshotIgnored": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A saved session was malformed, older than Fluxer's 60-second resume window, or saved for another gateway or shard count, so the shard starts a new session";
+    };
+    readonly "lifecycle.identifyPermitFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The sharding.identify coordinator failed to let a shard start a new session, so the SDK retries the connection";
+        readonly action: "Fix the coordinator's permit function";
+    };
+    readonly "lifecycle.domainMigration": {
+        readonly levels: readonly ["debug", "info"];
+        readonly meaning: "The Fluxer instance announced a web domain migration. When it is switched on, links and OAuth URLs use the announced web app host (Info). A switched-off migration is Debug";
+    };
+    readonly "lifecycle.observerCoalesced": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A connection-state observer was still busy, so an intermediate state was replaced by a newer one";
+    };
+    readonly "lifecycle.observerFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A connection-state observer threw or rejected";
+        readonly action: "Fix the observer callback";
+    };
+    readonly "lifecycle.taskFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "One run of a task started with client.schedule threw or failed. A repeating task keeps its schedule";
+        readonly action: "Fix the task, or handle the failure with the client-level onError";
+    };
+    readonly "lifecycle.tasksCancelled": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "Shutdown ended scheduled tasks that still had a run waiting or in progress, so those runs never happened or did not finish. The count is in fields.cancelled, and fields.running counts the runs cut off while in progress";
+        readonly action: "Shut down with drainMs to let running tasks finish first, and keep work that must survive a restart outside the SDK";
+    };
+    readonly "lifecycle.stopRequested": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "A stop signal or process signal asked the bot to stop";
+    };
+    readonly "lifecycle.botFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The runBot runner stopped because of a failure that no earlier record reported, and set the process exit code to 1. Setting reportFailure to false turns both off";
+        readonly action: "Read the error's hint";
+    };
+    readonly "lifecycle.shutdown": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "The client began shutting down";
+    };
+    readonly "lifecycle.draining": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "A shutdown with drainMs stopped accepting new events and waits for running handlers, waiting handler events, running scheduled tasks and REST requests to finish";
+    };
+    readonly "lifecycle.drained": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "All work running when the drain began finished in time, so shutdown continues without cancelling any";
+    };
+    readonly "lifecycle.drainTimedOut": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "The drain time ran out, so shutdown cancels the handlers, waiting events, scheduled tasks and REST requests that had not finished. The fields name how many";
+        readonly action: "Make handlers and tasks finish sooner, or raise drainMs if the process may take longer to stop";
+    };
+    readonly "lifecycle.shutdownComplete": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "The client finished shutting down and released its resources";
+    };
+    readonly "lifecycle.cleanupFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "A cleanup step failed during shutdown. Shutdown still ran the remaining steps";
+        readonly action: "Report it with the record's error if the SDK owns the failing step";
+    };
+    readonly "gateway.receive": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "A gateway frame was received";
+    };
+    readonly "gateway.send": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "A gateway frame was sent";
+    };
+    readonly "gateway.payloadReceived": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "The masked body of a received gateway frame, printed only in unsafe payload mode";
+    };
+    readonly "gateway.payloadSent": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "The masked body of a sent gateway frame, printed only in unsafe payload mode";
+    };
+    readonly "gateway.heartbeatAck": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "Fluxer acknowledged a heartbeat";
+    };
+    readonly "gateway.dispatch": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A dispatch event was received";
+    };
+    readonly "gateway.commandSent": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A command passed to gateway.send was sent to the gateway";
+    };
+    readonly "gateway.dispatchRejected": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A dispatch failed validation and was skipped. The failing field is in fields.field";
+        readonly action: "Report it if Fluxer's payloads changed, and include the field";
+    };
+    readonly "gateway.threadSkipped": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A thread in a community snapshot failed validation, so the channel cache does not hold it. The failing entry is in fields.field";
+        readonly action: "Report it if Fluxer's payloads changed, and include the field";
+    };
+    readonly "gateway.unknownDispatch": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A dispatch type that this SDK version does not handle was ignored";
+    };
+    readonly "gateway.unknownOpcode": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "An opcode that this SDK version does not handle was ignored";
+    };
+    readonly "gateway.identifyFilter": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A shard asked Fluxer not to send dispatch types that nothing uses";
+    };
+    readonly "gateway.ignoredEventRegistered": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A handler was registered for an event type that the running shards asked Fluxer to suppress";
+        readonly action: "Register the handler before connecting, or remove the type from gateway.ignoredEvents";
+    };
+    readonly "rest.request": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "One REST attempt finished, with its route, status, duration and Fluxer error code";
+    };
+    readonly "rest.retry": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A read is retried after a transient failure";
+    };
+    readonly "rest.busy": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A REST request failed with reason busy because the REST queue or the upload byte budget was full. It is logged at most once a minute, and every busy failure is counted in diagnostics().counters.restBusy";
+        readonly action: "Send fewer requests at once, or raise the limit the message names";
+    };
+    readonly "rest.rejected": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "Fluxer rejected a request with HTTP 401 or 403, usually a token or permission problem that persists. The message names the target channel or community when the route has one. It is logged even when the application handles the Result. When a handler or command fails with this rejection within one second and no onError hook receives the failure, the handler's failure record reports it instead. A later handler failure also logs its own record, because the Warn has already been emitted. Webhook and OAuth clients log rejected webhook tokens and OAuth client credentials the same way";
+        readonly action: "Follow fields.hint. A bot that expects these rejections can lower the rest category level";
+    };
+    readonly "rest.responseRejected": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A successful response to an SDK operation did not match the expected shape. The failing field or check is in fields.field";
+        readonly action: "Check test fixtures, or report it if Fluxer's responses changed";
+    };
+    readonly "rest.payloadSent": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "The masked body of a REST request, printed only in unsafe payload mode";
+    };
+    readonly "rest.payloadReceived": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "The masked body of a REST response, printed only in unsafe payload mode";
+    };
+    readonly "ratelimit.wait": {
+        readonly levels: readonly ["debug", "warn"];
+        readonly meaning: "A request was rate-limited and waits delayMs before retrying. Waits of a second or more are Warn";
+        readonly action: "Send fewer requests on that route if long waits repeat";
+    };
+    readonly "ratelimit.deadline": {
+        readonly levels: readonly ["debug", "warn"];
+        readonly meaning: "A rate-limit wait would pass the operation's timeout, so the request fails without waiting";
+        readonly action: "Raise timeoutMs, or send fewer requests on that route";
+    };
+    readonly "events.handlerFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "An event handler threw or failed. Other events keep running";
+        readonly action: "Fix the handler, or handle the failure with onError";
+    };
+    readonly "events.hookFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "An onError hook failed while it handled another failure";
+        readonly action: "Fix the onError hook";
+    };
+    readonly "events.overflow": {
+        readonly levels: readonly ["debug", "warn", "error"];
+        readonly meaning: "A subscription's queue exceeded its limit, so the subscription stopped";
+        readonly action: "Handle events faster, raise the pending limits or choose a dropping overflow policy";
+    };
+    readonly "events.dropped": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A full subscription queue dropped an event under its overflow policy";
+        readonly action: "Handle events faster or raise the pending limits";
+    };
+    readonly "events.discarded": {
+        readonly levels: readonly ["debug", "info"];
+        readonly meaning: "A subscription stopped with events still waiting in its queue, so they were discarded unhandled. Info means the client was closing, and Debug means the subscription itself closed. The count is in fields.discarded and in the eventsDropped.closed counter";
+        readonly action: "Shut down with drainMs to let waiting handler events run first";
+    };
+    readonly "events.refused": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "A draining shutdown did not deliver events that open subscriptions or collectors would have received, because it accepts no new events. The count is in fields.refused and in the eventsDropped.closed counter";
+    };
+    readonly "events.raw": {
+        readonly levels: readonly ["trace"];
+        readonly meaning: "A raw dispatch is being delivered to raw subscribers";
+    };
+    readonly "events.registeredAfterShutdown": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A subscription was registered after shutdown began, so it starts closed";
+        readonly action: "Register handlers before shutting down";
+    };
+    readonly "commands.executed": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A command finished";
+    };
+    readonly "commands.rejected": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A command did not run because a guard denied it, its cooldown was active or an argument was invalid";
+    };
+    readonly "commands.unmatched": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A message with the command prefix did not run a command. fields.reason holds the cause: an unknown name (the closest command is in fields.suggestion), a group without a subcommand or text the parser rejected, whose explanation the message gives";
+    };
+    readonly "commands.middlewareStopped": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A command did not run because middleware did not continue";
+    };
+    readonly "commands.failed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A command threw or failed";
+        readonly action: "Fix the command, or handle the failure with the router's onError";
+    };
+    readonly "commands.mentionPrefixUnavailable": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "The bot user ID needed for mention prefixes could not be read, so mention commands are skipped for a while";
+    };
+    readonly "collectors.callbackFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A collector callback threw or failed";
+        readonly action: "Fix the callback";
+    };
+    readonly "collectors.filterFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A collector filter threw or returned a non-boolean";
+        readonly action: "Make the filter return true or false without throwing";
+    };
+    readonly "collectors.failed": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A collector stopped because of a failure";
+        readonly action: "Read the collector's result for the error";
+    };
+    readonly "collectors.dropped": {
+        readonly levels: readonly ["debug"];
+        readonly meaning: "A full collector ignored an event while its last callback finished";
+    };
+    readonly "cache.policyFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A cache maxAgeMs function or a cache.onChange listener threw or returned an invalid value";
+        readonly action: "Fix that function or listener";
+    };
+    readonly "cache.changesDropped": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A cache.onChange listener had its maximum number of unfinished calls and waiting changes, so the oldest waiting change was dropped, or the client shut down while changes waited for its unfinished calls, so those were dropped. The record names the observer and how many changes it has dropped";
+        readonly action: "Make the listener finish its calls, or raise its concurrency or maxPendingChanges";
+    };
+    readonly "cleanup.progressFailed": {
+        readonly levels: readonly ["debug", "error"];
+        readonly meaning: "A message cleanup progress callback threw";
+        readonly action: "Fix the onProgress callback";
+    };
+    readonly "supervisor.spawn": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "The supervisor started a child process";
+    };
+    readonly "supervisor.spawnFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The supervisor could not start a child process";
+        readonly action: "Check the entry path and execArgv";
+    };
+    readonly "supervisor.exit": {
+        readonly levels: readonly ["info", "warn"];
+        readonly meaning: "A child process exited. Warn means it exited unexpectedly";
+    };
+    readonly "supervisor.crash": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "A child process stopped unexpectedly and cannot be restarted, because restart is false or its restarts are used up, so the supervisor shuts down";
+        readonly action: "Read the child's output records before this one, and raise restart.maxAttempts or remove restart: false if restarts should continue";
+    };
+    readonly "supervisor.restart": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "The supervisor restarts a child after a crash, within the restart budget";
+    };
+    readonly "supervisor.automaticSharding": {
+        readonly levels: readonly ["info"];
+        readonly meaning: "The supervisor counted the bot's communities for totalShards auto and chose the shard count and child processes";
+    };
+    readonly "supervisor.resharded": {
+        readonly levels: readonly ["warn", "error"];
+        readonly meaning: "Fluxer closed a shard of a child with 4011 (sharding required) under totalShards auto. Warn means the supervisor stopped every child, counted the communities again and started a larger plan, so events sent during the move were missed. Error means it had already moved 3 times within an hour or reached 16,384 shards, so it shut down";
+        readonly action: "For Error, check why the community count keeps growing, or choose a larger numeric totalShards";
+    };
+    readonly "supervisor.identifyPermitFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "The supervisor's identify coordinator rejected or threw instead of granting a child permission to start a new session, so the child retries as after a network failure";
+        readonly action: "Fix the permit function of the identify.coordinator supervisor option";
+    };
+    readonly "supervisor.memberRequestsLocal": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A supervised child asked its parent for a member request slot and got no answer, because the parent did not answer within one second or the child lost its message channel to it. The child then counted only its own member requests, so requests from other children could pass Fluxer's limit of 12 per account in 10 seconds, and Fluxer drops those without an answer. Logged once per child";
+        readonly action: "Read the supervisor records about this child before this one";
+    };
+    readonly "supervisor.childOutput": {
+        readonly levels: readonly ["info", "warn"];
+        readonly meaning: "A child printed a line that is not a log record. Standard error lines are Warn";
+    };
+    readonly "supervisor.outputFailed": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "Reading a child's standard output or standard error failed, so the parent stops forwarding that stream while the child keeps running. The stream is in fields.stream";
+        readonly action: "Read the record's error, and restart the supervisor if that child's output is needed";
+    };
+    readonly "supervisor.startupTimeout": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "A child did not become ready within startupTimeoutMs, so the supervisor shuts down";
+        readonly action: "Read the child's output records before this one, or raise startupTimeoutMs if startup needs longer";
+    };
+    readonly "supervisor.identifyUnacknowledged": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A child did not confirm sending Identify within 5 seconds of its permission, so the supervisor stops that child. Its restart follows the restart settings";
+        readonly action: "Read the child's output records before this one";
+    };
+    readonly "supervisor.terminated": {
+        readonly levels: readonly ["warn", "error"];
+        readonly meaning: "The supervisor force-terminates a child. Warn means the child did not exit within shutdownTimeoutMs of a stop request. Error means the child lost its message channel to the parent and kept running past shutdownTimeoutMs, so the supervisor shuts down";
+        readonly action: "Make the child's cleanup finish sooner, or raise shutdownTimeoutMs";
+    };
+    readonly "sdk.unknownDebugCategory": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "FLUXERLY_DEBUG names categories that do not exist";
+        readonly action: "Use the category names listed in fields.known";
+    };
+    readonly "sdk.unknownEnvironmentValue": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "FLUXERLY_LOG_FORMAT or FLUXERLY_LOG_COLOR has a value that is not recognized, so it is ignored";
+        readonly action: "Use one of the values in fields.accepted";
+    };
+    readonly "sdk.unsafePayloads": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "Unsafe payload logging is on, so Trace records include gateway and REST payloads that can contain private content. Bot tokens and other secrets stay masked";
+        readonly action: "Turn it off outside local debugging";
+    };
+    readonly "sdk.timerFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "An internal timer callback failed";
+        readonly action: "Report it with the record's error";
+    };
+    readonly "sdk.effectLog": {
+        readonly levels: readonly ["trace", "debug", "info", "warn", "error", "fatal"];
+        readonly meaning: "An Effect log call inside the SDK";
+    };
+    readonly "testing.unmatchedRequest": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A test client request matched no test route, so it received 404";
+        readonly action: "Add a route for the request";
+    };
+    readonly "testing.responderFailed": {
+        readonly levels: readonly ["error"];
+        readonly meaning: "A test route's responder threw, so the request failed as a network error";
+        readonly action: "Fix the responder";
+    };
+    readonly "testing.socketsLeftOpen": {
+        readonly levels: readonly ["warn"];
+        readonly meaning: "A test client left gateway sockets open after shutdown, and the test transport closed them";
+    };
+};
+/** Every log record code the SDK emits */
+export type LogCode = keyof typeof logCodes;
+//# sourceMappingURL=code-catalogue.d.ts.map