@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/message-errors.ts

@@ -0,0 +1,245 @@
+import type { ClientClosedError, ConfigurationError } from "./errors.js"
+import { operationErrorFields, operationErrorSettings, operationErrorText, type ApiErrorDetail } from "./api-errors.js"
+import { FluxerlyError, type OperationErrorOptions, type OperationOutcome, type OperationReason } from "./errors.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+
+/** An event subscription stopped because unread events exceeded its count or byte limit.
+ * The subscription does not restart or replay missed events
+ *
+ * @category Errors
+ */
+export class EventOverflowError extends FluxerlyError {
+    /** Discriminator for identifying queue overflow in an expected failure result */
+    readonly _tag = "EventOverflowError"
+    constructor(
+        /** Budget exceeded by the incoming event */
+        readonly limit: "messages" | "bytes",
+        /** Configured event-payload count when limit is messages, or source-JSON bytes when limit is bytes.
+         * A bulk deletion or reaction batch counts as one payload
+         */
+        readonly capacity: number,
+    ) {
+        super(
+            limit === "messages"
+                ? `The event subscription stopped because more than ${capacity} ${capacity === 1 ? "event was" : "events were"} waiting (maxPendingMessages)`
+                : `The event subscription stopped because waiting events exceeded ${capacity} bytes (maxPendingBytes)`,
+            {
+                code: "events.overflow",
+                hint: 'Handle events faster, raise maxPendingMessages or maxPendingBytes, or give a subscription overflow "dropOldest" or "dropNewest" so it drops events instead of stopping',
+                details: { limit, capacity },
+            },
+        )
+        this.name = this._tag
+    }
+}
+
+/** A second next call tried to read while the same default API pull subscription already had a pending read.
+ * Await that read before requesting another event
+ *
+ * @category Errors
+ */
+export class EventReadBusyError extends FluxerlyError {
+    /** Discriminator for identifying an overlapping pending read */
+    readonly _tag = "EventReadBusyError"
+    constructor() {
+        super("An event read is already pending for this subscription", {
+            code: "events.readBusy",
+            hint: "Await the pending next call before calling next again",
+        })
+        this.name = this._tag
+    }
+}
+
+/** A filtered event wait ended without a match or could not use its synchronous filter.
+ * A filter throw keeps the thrown value as cause. A non-boolean return is not retained
+ *
+ * @category Errors
+ */
+export class EventWaitError extends FluxerlyError {
+    /** Stable discriminator for a local timeout or synchronous filter failure */
+    readonly _tag = "EventWaitError"
+    constructor(
+        /** The reason timeout means no matching event was observed before the local deadline.
+         * The reason filter means the callback threw or failed to return a boolean synchronously, and a thrown value is the error's cause
+         */
+        readonly reason: "timeout" | "filter",
+        /** Optional underlying failure, such as the value thrown by the filter */
+        options?: { readonly cause?: unknown },
+    ) {
+        super(
+            reason === "timeout"
+                ? "No matching event arrived before the wait timed out"
+                : options?.cause === undefined
+                  ? "The event wait filter did not return true or false synchronously"
+                  : "The event wait filter threw. The thrown value is this error's cause",
+            {
+                code: `events.wait.${reason}`,
+                hint:
+                    reason === "timeout"
+                        ? "Raise timeoutMs or check that the awaited event is delivered to this bot"
+                        : "Make the filter return true or false synchronously without throwing",
+                cause: options?.cause,
+                details: { reason },
+            },
+        )
+        this.name = this._tag
+    }
+}
+
+/** A send, reply or forward ended without confirming that Fluxer created the message.
+ * Inspect outcome before retrying, since unknown means message creation may already have occurred.
+ * Even notDispatched or rejected can follow preparatory file uploads and does not prove rollback.
+ * Metadata contains no Fluxer response body or message content.
+ * A missing-permission rejection lists the permissions that sending needs in details.requiredPermissions, as
+ * ApiErrorDetail describes
+ *
+ * @category Errors
+ */
+export class MessageError extends FluxerlyError {
+    /** Discriminator for identifying expected message-creation failures */
+    readonly _tag = "MessageError"
+    /** Failure category, described by {@link OperationReason}.
+     * Busy also covers full local upload capacity, and a send never reports notFound
+     */
+    readonly reason: Exclude<OperationReason, "notFound">
+    /** Whether the message may have been created, using the same vocabulary as other operation errors.
+     * The outcome notDispatched means no message creation request was sent, and rejected means Fluxer answered with a
+     * rejection. Neither is proof of rollback, and preparatory file uploads may already have occurred.
+     * The outcome unknown means the message may already have been created, so another send can duplicate it
+     */
+    readonly outcome: OperationOutcome
+    /** HTTP status when received, or null for local failures and missing responses */
+    readonly status: number | null
+    /** Server-required wait in milliseconds when usable, otherwise null */
+    readonly retryAfterMs: number | null
+    /** Reviewed Fluxer rejection detail, or null when no safe classification is available */
+    readonly apiError: ApiErrorDetail | null
+    /** Safe local validation facts when the SDK can identify a failed input rule, otherwise null */
+    readonly inputValidation: InputValidationDetail | null
+    /** Create a send failure from its reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options: {
+        readonly reason: Exclude<OperationReason, "notFound">
+        readonly outcome: OperationOutcome
+        readonly status?: number | null | undefined
+        readonly retryAfterMs?: number | null | undefined
+        readonly apiError?: ApiErrorDetail | null | undefined
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        /** Unrecognized Fluxer error code, as in OperationErrorOptions */
+        readonly providerCode?: string | null | undefined
+        /** Failed response field or check, as in OperationErrorOptions */
+        readonly responseField?: string | null | undefined
+        readonly cause?: unknown
+    }) {
+        const fields = operationErrorFields({ ...options, operation: "send" })
+        super(operationErrorText("Message", fields), operationErrorSettings("message.send", fields, options.cause))
+        this.reason = fields.reason
+        this.outcome = options.outcome
+        this.status = fields.status
+        this.retryAfterMs = fields.retryAfterMs
+        this.apiError = fields.apiError
+        this.inputValidation = freezeInputValidationDetail(fields.inputValidation)
+        this.name = this._tag
+    }
+}
+
+/**
+ * A message lookup, read or change failed.
+ * Read operation to identify the call and reason to distinguish invalid input, full local capacity and Fluxer failures.
+ * A local get cache miss is successful undefined, not this error.
+ * Reads do not change messages, but a mutation with outcome unknown may already have taken effect.
+ * Error details contain no response body, credential or message content.
+ * A missing-permission rejection lists the permissions that the operation needs in details.requiredPermissions when
+ * the SDK knows them, as ApiErrorDetail describes.
+ * Cancellation in the default API and client closure have separate error tags and can also occur after mutation dispatch
+ *
+ * @category Errors
+ */
+export class MessageOperationError extends FluxerlyError {
+    /** Stable discriminator for expected message-management failures */
+    readonly _tag = "MessageOperationError"
+    /** The requested operation, independent of the gateway connection state */
+    readonly operation:
+        | "messages.get"
+        | "typing"
+        | "fetch"
+        | "publish"
+        | "fetchCrosspostSource"
+        | "fetchHistory"
+        | "search"
+        | "fetchReactionUsers"
+        | "pin"
+        | "unpin"
+        | "fetchPins"
+        | "edit"
+        | "delete"
+        | "deleteAttachment"
+        | "deleteMany"
+        | "deleteOwnMessages"
+        | "addReaction"
+        | "removeReaction"
+        | "removeUserReaction"
+        | "clearReaction"
+        | "clearReactions"
+    /** Failure category, described by {@link OperationReason}.
+     * Busy also covers full local upload capacity, and notFound applies to the target or its containing resource
+     */
+    readonly reason: OperationReason
+    /** Whether the request may have reached Fluxer, described by {@link OperationOutcome}.
+     * Preparatory file uploads may already have occurred even when no message or reaction request was dispatched.
+     * An unknown outcome includes server errors and missing or invalid success responses.
+     * Read calls do not mutate messages even when their request outcome is unknown
+     */
+    readonly outcome: OperationOutcome
+    /** HTTP status when available to this failure, otherwise null */
+    readonly status: number | null
+    /** Server-required wait in milliseconds when usable, otherwise null */
+    readonly retryAfterMs: number | null
+    /** Reviewed Fluxer rejection detail, or null when no safe classification is available */
+    readonly apiError: ApiErrorDetail | null
+    /** Safe explanation of the locally invalid property, or null when no input problem could be identified */
+    readonly inputValidation: InputValidationDetail | null
+    /** Create the failure from its operation, reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options: OperationErrorOptions<MessageOperationError["operation"]>) {
+        const fields = operationErrorFields(options)
+        super(operationErrorText("Message", fields), operationErrorSettings("message", fields, options.cause))
+        this.operation = fields.operation
+        this.reason = fields.reason
+        this.outcome = fields.outcome
+        this.status = fields.status
+        this.retryAfterMs = fields.retryAfterMs
+        this.apiError = fields.apiError
+        this.inputValidation = freezeInputValidationDetail(fields.inputValidation)
+        this.name = this._tag
+    }
+}
+
+/**
+ * Expected subscription-registration failures from invalid options or permanent client closure
+ *
+ * @category Errors
+ */
+export type RegistrationError = ConfigurationError | ClientClosedError
+/** Expected subscription-read failures from queue overflow or a competing pending read.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type EventReadError = EventOverflowError | EventReadBusyError
+/** Expected filtered event-wait failures, including invalid options, client closure, queue overflow, deadline expiry or a failed filter.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type EventWaitFailure = ConfigurationError | ClientClosedError | EventOverflowError | EventWaitError
+/** Expected message-creation failures shared by both entry points, including permanent client closure.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type SendError = MessageError | ClientClosedError
+/**
+ * Message lookup, management and reaction failures shared by both entry points. Native interruption remains outside this union
+ *
+ * @category Errors
+ */
+export type MessageOperationFailure = MessageOperationError | ClientClosedError

package/src/message-search.ts

@@ -0,0 +1,213 @@
+import type { GuildThreadChannel } from "./channels.js"
+import type { OperationOptions } from "./client.js"
+import type { MessageOperationOptions, Message, MessageCore } from "./messages.js"
+import type { PaginationQuery } from "./pagination.js"
+
+/** Community or channel in which to search messages visible to the bot.
+ * Supply at least guildId or channelId, as decimal strings, or both.
+ * Search uses the bot's current access permissions, not another account's permissions or access the bot had earlier.
+ * The SDK captures the supplied IDs once when the request or traversal starts
+ *
+ * @category Messages
+ */
+export type MessageSearchContext =
+    | {
+          /** Community ID defining the search context, as a decimal string */
+          readonly guildId: string
+          /** Optional channel context supplied alongside the community ID, as a decimal string */
+          readonly channelId?: string
+      }
+    | {
+          /** Optional community ID supplied with this channel context, as a decimal string */
+          readonly guildId?: string
+          /** Channel ID defining the search context, as a decimal string */
+          readonly channelId: string
+      }
+
+/**
+ * Author category used by Fluxer's message search: A user, bot or webhook sender
+ *
+ * @category Messages
+ */
+export type MessageSearchAuthorType = "user" | "bot" | "webhook"
+
+/** Kind of content to require or exclude in Fluxer's message search.
+ * The kind snapshot identifies copied content in a forwarded message
+ *
+ * @category Messages
+ */
+export type MessageSearchContentType =
+    "image" | "sound" | "video" | "file" | "sticker" | "embed" | "link" | "poll" | "snapshot"
+
+/**
+ * Embed category to require or exclude in Fluxer's message search
+ *
+ * @category Messages
+ */
+export type MessageSearchEmbedType = "image" | "video" | "sound" | "article"
+
+/** Filters and paging settings for one messages.search request.
+ * Fluxer searches an index that may not yet include recent edits or deletions.
+ * Search does not read message history or the local cache. Results are not added to the message cache.
+ * Omit a filter to leave that criterion unspecified. Fluxer combines and interprets the supplied search criteria.
+ * Unknown properties, invalid values and lists exceeding the documented limits are rejected locally.
+ * The SDK copies each filter array when the operation starts, so later changes to the array do not affect this request.
+ * All ID filters use decimal strings. Text limits count UTF-16 code units, the units used by JavaScript string.length
+ *
+ * @category Messages
+ */
+export interface MessageSearchQuery {
+    /** Maximum indexed messages requested, an integer from 1 through 25, default 25 */
+    readonly limit?: number
+    /** Numbered result page, an integer from 1 through 400 with 1 meaning the first page. Defaults to 1 */
+    readonly page?: number
+    /** Include message IDs smaller than this decimal ID */
+    readonly maxId?: string
+    /** Include message IDs greater than this decimal ID */
+    readonly minId?: string
+    /** Text for Fluxer to search, from 1 through 1,024 UTF-16 code units, without local trimming */
+    readonly content?: string
+    /** Multiple search texts, at most 100 strings, each from 1 through 1,024 UTF-16 code units */
+    readonly contents?: readonly string[]
+    /** Contiguous phrases to match, at most 10 strings, each from 1 through 1,024 UTF-16 code units */
+    readonly exactPhrases?: readonly string[]
+    /** Limit matches to these channel IDs, at most 500 decimal strings */
+    readonly channelIds?: readonly string[]
+    /** Exclude matches from these channels, at most 500 decimal ID strings */
+    readonly excludeChannelIds?: readonly string[]
+    /** Author categories to include, at most 20 entries */
+    readonly authorTypes?: readonly MessageSearchAuthorType[]
+    /** Author categories to exclude, at most 20 entries */
+    readonly excludeAuthorTypes?: readonly MessageSearchAuthorType[]
+    /** Match messages from these author IDs, at most 100 decimal strings */
+    readonly authorIds?: readonly string[]
+    /** Exclude messages from these author IDs, at most 100 decimal strings */
+    readonly excludeAuthorIds?: readonly string[]
+    /** Match account mentions using these IDs, at most 100 decimal strings */
+    readonly mentions?: readonly string[]
+    /** Exclude matches mentioning these accounts, at most 100 decimal ID strings */
+    readonly excludeMentions?: readonly string[]
+    /** Require or exclude messages that Fluxer's index marks as mentioning @everyone or @here */
+    readonly mentionedEveryone?: boolean
+    /** Require pinned messages with true, or unpinned messages with false, according to the index */
+    readonly pinned?: boolean
+    /** Content categories to require, at most 20 entries */
+    readonly has?: readonly MessageSearchContentType[]
+    /** Content categories to exclude, at most 20 entries */
+    readonly excludeHas?: readonly MessageSearchContentType[]
+    /** Embed categories to require, at most 20 entries, including generated and explicitly supplied embeds */
+    readonly embedTypes?: readonly MessageSearchEmbedType[]
+    /** Embed categories to exclude, at most 20 entries, including generated and explicitly supplied embeds */
+    readonly excludeEmbedTypes?: readonly MessageSearchEmbedType[]
+    /** Embed provider names to match, at most 50 strings of 1 through 256 UTF-16 code units each */
+    readonly embedProviders?: readonly string[]
+    /** Embed provider names to exclude, at most 50 strings of 1 through 256 UTF-16 code units each */
+    readonly excludeEmbedProviders?: readonly string[]
+    /** Link hostnames to match, at most 100 strings of 1 through 255 UTF-16 code units each */
+    readonly linkHostnames?: readonly string[]
+    /** Link hostnames to exclude, at most 100 strings of 1 through 255 UTF-16 code units each */
+    readonly excludeLinkHostnames?: readonly string[]
+    /** Attached file names to match, at most 100 strings of 1 through 1,024 UTF-16 code units each */
+    readonly attachmentFilenames?: readonly string[]
+    /** Attached file names to exclude, at most 100 strings of 1 through 1,024 UTF-16 code units each */
+    readonly excludeAttachmentFilenames?: readonly string[]
+    /** Attached file extensions to match, at most 50 strings of 1 through 32 UTF-16 code units each */
+    readonly attachmentExtensions?: readonly string[]
+    /** Attached file extensions to exclude, at most 50 strings of 1 through 32 UTF-16 code units each */
+    readonly excludeAttachmentExtensions?: readonly string[]
+    /** Rank results by timestamp or relevance, default timestamp */
+    readonly sortBy?: "timestamp" | "relevance"
+    /** Ascending or descending result order, default desc */
+    readonly sortOrder?: "asc" | "desc"
+    /** Request results from channels Fluxer marks NSFW, default false. In an age-restricted community, guild search includes NSFW results for eligible callers, including bots, even when omitted or false. Channel access checks still apply */
+    readonly includeNsfw?: boolean
+}
+
+/** Channel information supplied beside message search results.
+ * This frozen snapshot is not a complete channel, cached channel or permission check
+ *
+ * @category Messages
+ */
+export interface MessageSearchChannel {
+    /** Channel ID as a decimal string */
+    readonly id: string
+    /** Owning community ID, when Fluxer supplied it */
+    readonly guildId?: string
+    /** Observed channel name, when supplied. An unnamed group DM has null, and other private channels may omit it */
+    readonly name?: string | null
+    /** Fluxer's numeric channel type, including unrecognized future values */
+    readonly type: number
+}
+
+/** Successful search response indicating that Fluxer is still preparing an index.
+ * No messages or result total are available yet. Retry later with another explicit search request.
+ * The SDK does not poll or retry indexing automatically
+ *
+ * @category Messages
+ */
+export interface MessageSearchIndexingPage {
+    /** True distinguishes this response from a MessageSearchResultsPage */
+    readonly indexing: true
+}
+
+/** Search results returned once Fluxer's index can answer the request.
+ * The page and its nested results are frozen. Later index updates can change later pages and totals.
+ * Check indexing before reading results, since search can instead return MessageSearchIndexingPage
+ *
+ * @category Messages
+ */
+export interface MessageSearchResultsPage<M extends MessageCore = Message> {
+    /** False distinguishes this response from an index-preparation response */
+    readonly indexing: false
+    /** Indexed message snapshots using the client's messageFields selection, without extra fetches or cache writes */
+    readonly messages: readonly M[]
+    /** One channel snapshot per distinct channel in messages that is not a thread, without extras, private recipient lists or permission data */
+    readonly channels: readonly MessageSearchChannel[]
+    /** One thread snapshot per distinct thread in messages, with membership set on each thread the bot has joined.
+     * Each message's channelId names exactly one entry of channels or threads. These snapshots never enter the channel cache
+     */
+    readonly threads: readonly GuildThreadChannel[]
+    /** Indexed match count observed with this response, not a stable count for a multi-page run */
+    readonly total: number
+    /** Page capacity Fluxer reported for this response, not necessarily the number of returned messages */
+    readonly hitsPerPage: number
+    /** Page number Fluxer applied, starting at 1 */
+    readonly page: number
+}
+
+/** Successful outcome of one messages.search request.
+ * Branch on indexing before accessing result fields
+ *
+ * @category Messages
+ */
+export type MessageSearchPage<M extends MessageCore = Message> = MessageSearchIndexingPage | MessageSearchResultsPage<M>
+
+/** Limit how many messages and pages messages.iterateSearch can read.
+ * Each consumption starts at page 1 for the given context and filters, then reads later numbered pages as Fluxer's total requires.
+ * Limits are captured once when that consumption starts.
+ * Fluxer supports at most 400 numbered pages. If more results remain after page 400, traversal fails with PaginationError reason pageLimit.
+ * No background prefetch runs. An indexing response fails traversal with PaginationError reason indexing rather than polling
+ *
+ * @category Messages
+ */
+export interface MessageSearchIterationLimits extends PaginationQuery {
+    /** Maximum messages per request, an integer from 1 through 25, default 25.
+     * Request capacity is the smaller of this value and maxItems, fixed throughout the scan to preserve page offsets
+     */
+    readonly pageSize?: number
+}
+
+/** Deadline for one explicit search request.
+ * For iterateSearch, the deadline applies separately to each page request, not to the entire traversal
+ *
+ * @category Messages
+ */
+export interface MessageSearchOptions extends MessageOperationOptions {}
+
+/** Search settings for the Promise and Result API, including AbortSignal cancellation.
+ * The signal affects this explicit request or this consumption's iterator pulls, not other callers.
+ * The Effect entry point uses interruption instead
+ *
+ * @category Messages
+ */
+export interface DefaultMessageSearchOptions extends MessageSearchOptions, OperationOptions {}