@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/expressions.ts

@@ -0,0 +1,198 @@
+import type { ModerationOptions, DefaultModerationOptions } from "./guilds.js"
+
+/** Address a custom emoji or sticker by its owning community and resource ID.
+ * A fetched emoji or sticker already contains these IDs and can be passed wherever this reference is accepted
+ *
+ * @category Emoji and stickers
+ */
+export interface ExpressionReference {
+    /** Owning guild ID */
+    readonly guildId: string
+    /** Emoji or sticker ID */
+    readonly id: string
+}
+
+/** A community's custom emoji identity, name and animation flag.
+ * Pass this snapshot to message reaction helpers or emoji management methods. It contains no image bytes or
+ * creator account, and it does not update when the emoji is renamed or deleted
+ *
+ * @category Emoji and stickers
+ */
+export interface GuildEmoji extends ExpressionReference {
+    /** Emoji name */
+    readonly name: string
+    /** Whether the image is animated */
+    readonly animated: boolean
+}
+
+/** A community's custom sticker identity and display metadata, including its description and suggestion tags.
+ * This frozen snapshot contains no image bytes or creator account. Use stickers.edit to replace metadata,
+ * not to replace the underlying image
+ *
+ * @category Emoji and stickers
+ */
+export interface GuildSticker extends GuildEmoji {
+    /** Provider description, including empty text */
+    readonly description: string
+    /** Frozen suggestion tags in provider order */
+    readonly tags: readonly string[]
+}
+
+/** Public name and animation information returned by fetchMetadata without requiring source-community membership.
+ * The allowCloning flag is a provider hint for deciding whether to attempt a clone, not proof of access to either community.
+ * This is not the full community-owned sticker or emoji management record
+ *
+ * @category Emoji and stickers
+ */
+export interface ExpressionMetadata extends GuildEmoji {
+    /** Provider's current cloning hint, not authorization or a guarantee that a later clone will succeed */
+    readonly allowCloning: boolean
+}
+
+/** Upload an image as a named custom community emoji for messages and reactions.
+ * Supply encoded image bytes, because the SDK does not read a file or fetch an image URL
+ * @example
+ * ```ts
+ * import type { Client, GuildEmoji, GuildSticker, MessageReference } from "@neontechspace/fluxerly"
+ * export function expressionExample(client: Client, guildId: string, image: string) {
+ *     return client.emojis.create(guildId, { name: "build_passed", image })
+ * }
+ * export function renameStickerExample(client: Client, sticker: GuildSticker) {
+ *     return client.stickers.edit(sticker, { ...sticker, name: "Build passed" })
+ * }
+ * export function useEmojiExample(client: Client, message: MessageReference, emoji: GuildEmoji) {
+ *     return client.messages.addReaction(message, emoji)
+ * }
+ * ```
+ *
+ * @category Emoji and stickers
+ */
+export interface EmojiCreate {
+    /** 2–32 ASCII letters, digits or underscores */
+    readonly name: string
+    /** Base64 image data or an image data URI, at most 512 KiB decoded.
+     * Fluxer validates the actual format, dimensions, moderation and community capacity.
+     * No file is read implicitly. Callers own encoding and the lifetime of their original bytes
+     */
+    readonly image: string
+}
+
+/** Upload a named custom sticker with optional description and suggestion tags.
+ * Supply image bytes as base64 or a data URI, as with EmojiCreate. Fluxer validates image format, dimensions,
+ * moderation and community capacity after local input validation
+ *
+ * @category Emoji and stickers
+ */
+export interface StickerCreate {
+    /** Sticker name, 2–30 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming.
+     * The original string is sent unchanged
+     */
+    readonly name: string
+    /** Omitted/null means no description. Otherwise the value must contain 1–500 normalized UTF-16 code units.
+     * Validation removes U+000C and U+202E and trims surrounding whitespace. The original string is sent unchanged
+     */
+    readonly description?: string | null
+    /** Up to ten tags of 1–30 normalized UTF-16 code units each. Omitted means empty. Validation removes U+000C and
+     * U+202E and trims surrounding whitespace without changing the strings sent. Entries are copied by index when the operation starts
+     */
+    readonly tags?: readonly string[]
+    /** Base64 image data or image data URI, at most 512 KiB decoded */
+    readonly image: string
+}
+
+/**
+ * Rename an emoji without replacing its image
+ *
+ * @category Emoji and stickers
+ */
+export interface EmojiEdit {
+    /** Replacement name, 2–32 ASCII letters, digits or underscores */
+    readonly name: string
+}
+
+/** Replace sticker metadata without reading or merging remote state. Images cannot be replaced.
+ * A fetched sticker can be spread into this input. Its matching identity and animation fields are ignored
+ *
+ * @category Emoji and stickers
+ */
+export interface StickerEdit {
+    /** Required replacement name, 2–30 normalized UTF-16 code units. Validation removes U+000C and U+202E and
+     * trims surrounding whitespace without changing the string sent
+     */
+    readonly name: string
+    /** Required replacement description, 1–500 normalized UTF-16 code units. Empty/null clears it. Validation removes
+     * U+000C and U+202E and trims surrounding whitespace without changing a nonempty string sent
+     */
+    readonly description: string | null
+    /** Required replacement list, at most ten tags of 1–30 normalized UTF-16 code units. [] clears it. Validation
+     * removes U+000C and U+202E and trims surrounding whitespace without changing the strings sent. Entries are copied by index when the operation starts
+     */
+    readonly tags: readonly string[]
+}
+
+/** Results of creating emoji or stickers in one batch request.
+ * Inspect both lists even when the HTTP request succeeded. Entries in success were created independently of
+ * failures, so repeating the whole batch can duplicate successful creations. Provider order does not map failures
+ * back to input positions when names repeat
+ *
+ * @category Emoji and stickers
+ */
+export interface ExpressionBatch<A> {
+    /** Created resources. They remain created even when another entry fails */
+    readonly success: readonly A[]
+    /** Failed names in provider order. Duplicate names cannot be correlated to an input index.
+     * Raw localized provider error text is deliberately excluded from SDK data and diagnostics
+     */
+    readonly failed: readonly {
+        /** Name reported for a failed creation, which may identify more than one input when names repeat */
+        readonly name: string
+    }[]
+}
+
+/** Choose whether deleting a community emoji or sticker also requests removal of its image asset.
+ * The inherited timeout and auditReason follow ModerationOptions.
+ * Removing the image is a separate queued job. Deleting the community entry does not wait for it to finish
+ *
+ * @category Options
+ */
+export interface ExpressionDeleteOptions extends ModerationOptions {
+    /** False/default removes the community entry without asking to purge its image.
+     * True additionally requests irreversible queued asset/CDN removal and requires Fluxer's expression-purge feature.
+     * HTTP success does not mean the purge job has finished. Failure after dispatch can leave either effect applied
+     */
+    readonly purge?: boolean
+}
+
+/**
+ * Starts immediately. Cancellation awaits cleanup but cannot undo deletion or queued purging
+ *
+ * @category Options
+ */
+export interface DefaultExpressionDeleteOptions extends ExpressionDeleteOptions, DefaultModerationOptions {}
+
+/** Public presentation of the community that owns a custom emoji or sticker, returned by fetchSource.
+ * Fluxer returns it for a public source community, or for a private one the bot is a member of. It is a frozen snapshot with
+ * no member, channel or permission data, and reading it grants no access to the community or the expression
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * export async function sourceBadgeExample(client: Client, emojiId: string) {
+ *     const source = await client.emojis.fetchSource(emojiId)
+ *     return source.map((guild) => `${guild.name}${guild.features.includes("VERIFIED") ? " (verified)" : ""}`)
+ * }
+ * ```
+ *
+ * @category Emoji and stickers
+ */
+export interface ExpressionSourceGuild {
+    /** Source guild ID as a decimal string */
+    readonly id: string
+    /** Source community name at the time of the read */
+    readonly name: string
+    /** Icon hash of the source community, or null when it has no icon. Build an image URL with the asset helpers */
+    readonly icon: string | null
+    /** Badge features in provider order. Fluxer currently limits them to VERIFIED, PARTNERED and DISCOVERABLE.
+     * A badge string added by Fluxer later is retained unchanged rather than failing the read, so compare against known names
+     */
+    readonly features: readonly string[]
+}

package/src/failures.ts

@@ -0,0 +1,55 @@
+import type { EventName } from "./events.js"
+
+/** What failed.
+ * The kind handler is an event or command callback, and overflow is a subscription stopped by a full queue.
+ * The kind collector is a message or reaction collector callback, and filter is a collector filter.
+ * The kind progress is a message cleanup onProgress callback, cache is a cache maxAgeMs duration callback or a cache.onChange listener,
+ * observer is a state observer and task is one run of a client.schedule task.
+ * A failing onError hook is never reported to a hook again: It is logged with the original failure and counted in
+ * diagnostics().counters.hookFailures
+ *
+ * @category Logging and diagnostics
+ */
+export type FailureKind = "handler" | "overflow" | "collector" | "filter" | "progress" | "cache" | "observer" | "task"
+
+/**
+ * IDs of the message involved in a failure, without its content
+ *
+ * @category Logging and diagnostics
+ */
+export interface FailureMessageReference {
+    /** Message ID */
+    readonly id: string
+    /** Channel ID */
+    readonly channelId: string
+    /** Guild ID when the message belongs to a community */
+    readonly guildId?: string
+}
+
+/**
+ * A failure outside any returned result, delivered to an onError hook or logged at Error with its full error.
+ * Reports delivered to a hook log at Debug without repeating the error. A handler failure caused by an HTTP 401 or 403
+ * rejection replaces that rejection's Warn only when reported within one second, otherwise both records appear.
+ * The error is the real value that the application callback threw or rejected with, or the SDK error that stopped the work.
+ * The report holds IDs only, never message content
+ *
+ * @category Logging and diagnostics
+ */
+export interface FailureReport {
+    /** What failed */
+    readonly kind: FailureKind
+    /** The original thrown, rejected or failed value */
+    readonly error: unknown
+    /** Event whose delivery failed, when the failure belongs to an event subscription */
+    readonly event?: EventName
+    /** Prefix command name, when a command callback failed */
+    readonly command?: string
+    /** Identifier of the subscription that owns the failed work, matching Subscription.id and log records */
+    readonly subscriptionId?: string
+    /** IDs of the message being handled, when there was one */
+    readonly message?: FailureMessageReference
+    /** Readable multi-line summary with the error's name, application code, message, stack and cause chain.
+     * Credential patterns and the client's configured credentials are masked, without changing the original error
+     */
+    describe(): string
+}

package/src/gateway.ts

@@ -0,0 +1,86 @@
+import type { ClientClosedError } from "./errors.js"
+import { FluxerlyError, operationDetails } from "./errors.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+
+/**
+ * Why gateway.send did not hand a command to the shard's connection.
+ * The reason input means the shard ID, opcode or data is malformed, cannot be encoded as JSON, or encodes to more than
+ * Fluxer's 4,096-byte message limit. The reason reserved means the opcode belongs to the SDK-managed session
+ * (heartbeat, Identify or Resume) or is a server-only opcode that Fluxer answers by closing the connection.
+ * The reason notOwned means this client does not own the shard, and notReady means the shard is not currently
+ * Connected or lost its connection before the command reached the socket.
+ * The reason busy means 500 earlier gateway.send commands on that shard are still waiting for the pacing budget.
+ * Cancelling an unsent command immediately releases its queue capacity, even while the pacing window is full.
+ * None of these failures sent anything
+ *
+ * @category Errors
+ */
+export class GatewaySendError extends FluxerlyError {
+    /** Stable expected-failure discriminator */
+    readonly _tag = "GatewaySendError"
+    /** Local shard the command was for, or null when the supplied shard ID was not a non-negative integer */
+    readonly shardId: number | null
+    /** Requested opcode, or null when the supplied opcode was not a non-negative integer */
+    readonly opcode: number | null
+    /** Why the command was not sent */
+    readonly reason: "input" | "reserved" | "notOwned" | "notReady" | "busy"
+    /** Safe explanation of the invalid argument for reason input, otherwise null. It never contains the rejected value */
+    readonly inputValidation: InputValidationDetail | null
+
+    /** Describe a command that was not sent. Construction has no side effects */
+    constructor(options: {
+        /** Why the command was not sent */
+        readonly reason: GatewaySendError["reason"]
+        /** Local shard ID, or null when the supplied value was not a valid shard ID. Defaults to null */
+        readonly shardId?: number | null | undefined
+        /** Requested opcode, or null when the supplied value was not a valid opcode. Defaults to null */
+        readonly opcode?: number | null | undefined
+        /** Safe input detail for reason input. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        /** Underlying failure retained as the error's cause, such as a JSON encoding error */
+        readonly cause?: unknown
+    }) {
+        const { reason, shardId = null, opcode = null, inputValidation = null } = options
+        const target = shardId === null ? "the requested shard" : `shard ${shardId}`
+        super(
+            `Gateway command${opcode === null ? "" : ` with opcode ${opcode}`} was not sent on ${target}: ${
+                // The input detail names the invalid argument, such as an unsupported option
+                reason === "input" && inputValidation !== null ? inputValidation.explanation : explanations[reason]
+            }`,
+            {
+                code: `gateway.send.${reason}`,
+                hint: hints[reason],
+                cause: options.cause,
+                details: operationDetails({ reason, shardId, opcode }),
+            },
+        )
+        this.name = this._tag
+        this.shardId = shardId
+        this.opcode = opcode
+        this.reason = reason
+        this.inputValidation = freezeInputValidationDetail(inputValidation)
+    }
+}
+
+const explanations: Record<GatewaySendError["reason"], string> = {
+    input: "The shard ID, opcode or command data is invalid",
+    reserved: "The SDK manages this opcode itself, or only Fluxer sends it",
+    notOwned: "This client does not run the shard",
+    notReady: "The shard is not connected",
+    busy: "Too many earlier commands are waiting, because the SDK sends at most 500 commands per minute on each connection",
+}
+
+const hints: Record<GatewaySendError["reason"], string> = {
+    input: "Pass a non-negative integer shard ID and opcode, and JSON data that encodes to at most 4,096 bytes with its opcode",
+    reserved: "Use the SDK's own methods, such as presence.set, instead of sending session opcodes",
+    notOwned: "Send on a shard listed in client.shards",
+    notReady: "Retry after the shard is Connected again, for example after observing client state",
+    busy: "Wait for earlier gateway.send operations to complete before sending more",
+}
+
+/**
+ * Expected gateway.send failures in both APIs
+ *
+ * @category Errors
+ */
+export type GatewaySendFailure = GatewaySendError | ClientClosedError