@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/member-search.ts

@@ -0,0 +1,152 @@
+import type { PaginationQuery } from "./pagination.js"
+
+/**
+ * Fluxer's known sources for a community membership recorded by the indexed member-search service
+ *
+ * @category Guilds and members
+ */
+export const GuildMemberJoinSourceTypes: Readonly<{
+    /** The member created the community */
+    Creator: 0
+    /** The member joined through a regular invitation code */
+    InstantInvite: 1
+    /** The member joined through the community's custom invitation code */
+    VanityUrl: 2
+    /** The bot was added through a bot installation invitation */
+    BotInvite: 3
+    /** The member was added by an administrator */
+    AdminForceAdd: 4
+    /** The member joined through the public community directory */
+    Discovery: 6
+}> = Object.freeze({
+    Creator: 0,
+    InstantInvite: 1,
+    VanityUrl: 2,
+    BotInvite: 3,
+    AdminForceAdd: 4,
+    Discovery: 6,
+})
+
+/**
+ * One known Fluxer community-member join source
+ *
+ * @category Guilds and members
+ */
+export type GuildMemberJoinSourceType = (typeof GuildMemberJoinSourceTypes)[keyof typeof GuildMemberJoinSourceTypes]
+
+/**
+ * Search Fluxer's community member index by text, roles, join dates or how members joined.
+ * Search results may lag behind current membership and profile changes. They contain only search fields, not complete GuildMember objects, and do not come from the SDK cache.
+ * Fluxer requires a member-management permission for every search.
+ * Join-source and source-invite filters require ManageGuild. The SDK checks for ManageGuild before sending those filters because Fluxer would otherwise ignore them without an error. Filter arrays are copied by index when the operation starts.
+ * Timestamps use whole Unix seconds. Unknown keys and values outside the documented
+ * bounds fail locally before the POST. The provider can return an empty, non-indexing page when its search service is
+ * unavailable
+ *
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ *
+ * export function memberSearchExample(client: Client, guildId: string) {
+ *     const page = client.members.search(guildId, { query: "alex", roleIds: ["10"] })
+ *     const hits = client.members.iterateSearch(guildId, { isBot: false }, { maxItems: 100 })
+ *     return { page, hits }
+ * }
+ * ```
+ *
+ * @category Guilds and members
+ */
+export interface MemberSearchQuery {
+    /** Text matched by Fluxer against indexed usernames, display names, nicknames, discriminators and user IDs. At most 100 UTF-16 code units */
+    readonly query?: string
+    /** Results in this offset page, 1–100, default 25 */
+    readonly limit?: number
+    /** Zero-based indexed-result offset, a nonnegative safe integer, default 0. It does not mark a fixed position in an unchanging result set */
+    readonly offset?: number
+    /** Require every supplied role ID. At most 10 distinct decimal role IDs. An empty list has no filtering effect */
+    readonly roleIds?: readonly string[]
+    /** Include members whose indexed community-join time is at or after this nonnegative whole Unix-second value */
+    readonly joinedAtAfterSeconds?: number
+    /** Include members whose indexed community-join time is at or before this nonnegative whole Unix-second value */
+    readonly joinedAtBeforeSeconds?: number
+    /** Include members whose indexed account-creation time is at or after this nonnegative whole Unix-second value */
+    readonly userCreatedAtAfterSeconds?: number
+    /** Include members whose indexed account-creation time is at or before this nonnegative whole Unix-second value */
+    readonly userCreatedAtBeforeSeconds?: number
+    /** Require one of these indexed membership sources. At most 10 distinct values and requires ManageGuild */
+    readonly joinSourceTypes?: readonly GuildMemberJoinSourceType[]
+    /** Require one of these indexed invite codes. At most 10 distinct values and requires ManageGuild. Codes are never included in SDK diagnostics */
+    readonly sourceInviteCodes?: readonly string[]
+    /** Include only bot or only non-bot indexed members */
+    readonly isBot?: boolean
+    /** Fluxer relevance or indexed join-time ordering. Omission uses indexed join time */
+    readonly sortBy?: "joinedAt" | "relevance"
+    /** Indexed join-time direction. Omission uses descending. Fluxer ignores this when sorting by relevance */
+    readonly sortOrder?: "asc" | "desc"
+}
+
+/** A member matched by the search index, with indexed identity, roles and available membership-source details.
+ * Call members.fetch with guildId and userId when current member details are needed. This frozen hit does not populate
+ * the member cache and cannot establish current membership or permissions
+ *
+ * @category Guilds and members
+ */
+export interface MemberSearchHit {
+    /** Decimal guild ID, equal to the requested guild */
+    readonly guildId: string
+    /** Decimal member user ID */
+    readonly userId: string
+    /** Indexed account username */
+    readonly username: string
+    /** Indexed four-digit account discriminator */
+    readonly discriminator: string
+    /** Indexed account-wide display name, null when absent. The display.name helper reads it */
+    readonly displayName: string | null
+    /** Indexed community nickname, null when absent */
+    readonly nickname: string | null
+    /** Explicit indexed role IDs, not effective permissions or the implicit everyone role */
+    readonly roleIds: readonly string[]
+    /** Indexed community-join time as a nonnegative whole Unix-second value */
+    readonly joinedAtSeconds: number
+    /** Indexed bot classification */
+    readonly isBot: boolean
+    /** Indexed membership source, or null when absent or redacted because the caller lacks ManageGuild */
+    readonly joinSourceType: GuildMemberJoinSourceType | null
+    /** Indexed invite code, or null when absent or redacted because the caller lacks ManageGuild */
+    readonly sourceInviteCode: string | null
+    /** Decimal inviter user ID, or null when absent or redacted because the caller lacks ManageGuild */
+    readonly inviterId: string | null
+}
+
+/**
+ * Matching indexed members and counts from one search request.
+ * Counts and order describe a changing index, not a complete membership snapshot.
+ * When indexing is true, Fluxer accepted the request but is building the community index.
+ * Wait and issue a new page request rather than treating that empty page as completion
+ *
+ * @category Guilds and members
+ */
+export interface MemberSearchPage {
+    /** Decimal guild ID, equal to the requested guild */
+    readonly guildId: string
+    /** Frozen indexed hit observations. This does not admit or replace member-cache entries */
+    readonly members: readonly MemberSearchHit[]
+    /** Number of returned members in this page */
+    readonly pageResultCount: number
+    /** Indexed matches observed for this request, which can change before a later offset page */
+    readonly totalResultCount: number
+    /** Whether Fluxer reported that it is currently building this community's member index */
+    readonly indexing: boolean
+}
+
+/** Limit how much work members.iterateSearch may perform while reading matching indexed members.
+ * The maxItems option is required through PaginationQuery. Each consumption requests pages only as needed and yields each user
+ * at most once, but concurrent index changes can skip members. Index-building pages fail with PaginationError/indexing,
+ * and an empty page that cannot advance fails with cursorStalled rather than silently reporting completion
+ *
+ * @category Guilds and members
+ */
+export interface MemberSearchIterationLimits extends PaginationQuery {
+    /** Indexed hits requested per POST, 1–100 and default 100 */
+    readonly pageSize?: number
+}

package/src/message-cleanup.ts

@@ -0,0 +1,308 @@
+import type { OperationOptions } from "./client.js"
+import type { MessageOperationError } from "./message-errors.js"
+import {
+    operationErrorMessage,
+    operationFailureHint,
+    safeProviderCode,
+    safeResponseField,
+    type ApiErrorDetail,
+} from "./api-errors.js"
+import { FluxerlyError, operationDetails } from "./errors.js"
+import { freezeInputValidationDetail, type InputValidationDetail } from "./input-validation.js"
+import type { Message, MessageCore, MessageOperationOptions } from "./messages.js"
+
+/** Choose messages for previewCleanup without deleting them.
+ * Set explicit scan and selection limits, and supply authorId, filter, or both.
+ * With both supplied, a message must match the author before the filter runs.
+ * Messages are inspected newest first, using this client's messageFields selection.
+ * The SDK keeps the preview and deletion plan only in memory, not on disk
+ *
+ * @category Messages
+ */
+export interface MessageCleanupSelection<M extends MessageCore = Message> {
+    /** Select only messages authored by this account ID, as a decimal string */
+    readonly authorId?: string
+    /** Return true to select a message, false to skip it. Runs synchronously, so do not block or return a Promise.
+     * A throw or non-boolean return fails preview with reason filter, before any deletion.
+     * Cancellation and timeouts cannot preempt blocking JavaScript. Mistaken asynchronous work is not awaited or cancelled
+     */
+    readonly filter?: (message: M) => boolean
+    /** Maximum history messages to fetch and inspect, a required integer from 1 through 10,000 */
+    readonly maxScanned: number
+    /** Maximum selected snapshots to keep in the plan, a required integer from 1 through 10,000 */
+    readonly maxSelected: number
+}
+
+/** Why preview stopped: An empty history page, the scan cap, or the selected-message cap.
+ * The scanLimit and selectionLimit reasons do not mean that the channel's history was exhausted
+ *
+ * @category Messages
+ */
+export type MessageCleanupStopReason = "historyExhausted" | "scanLimit" | "selectionLimit"
+
+/** Frozen preview of the exact messages to inspect before requesting deletion.
+ * Pass the original object to cleanup on the client that produced it. Reconstructed JSON and plans from another client are rejected.
+ * Cleanup marks a valid plan as used before it sends any deletion request, even if it then fails before sending one.
+ * A consumed plan cannot be retried. Use a fresh preview or explicit deleteMany requests after application-owned reconciliation.
+ * The plan does not store a reference to its client or save requests to disk. The SDK cannot recover it after a crash
+ *
+ * @category Messages
+ */
+export interface MessageCleanupPlan<M extends MessageCore = Message> {
+    /** Channel inspected by preview and the only channel this plan can delete from */
+    readonly channelId: string
+    /** Exact selected message snapshots, newest first. Changes after preview do not update this selection */
+    readonly selectedMessages: readonly M[]
+    /** Number of messages inspected, including messages rejected by the selection */
+    readonly scannedCount: number
+    /** Condition that ended preview. Even historyExhausted describes an observed empty page, not a stable remote snapshot */
+    readonly stopReason: MessageCleanupStopReason
+}
+
+/** Exact IDs in one cleanup bulk-delete request, containing at most 100 IDs.
+ * Batches run sequentially. A successful HTTP response means Fluxer accepted the request. It does not prove that every ID existed or was deleted
+ *
+ * @category Messages
+ */
+export interface MessageCleanupBatch {
+    /** Submission position, with 0 identifying the first batch */
+    readonly batchIndex: number
+    /** Selected IDs assigned to this request, in preview order. Cleanup does not rescan history */
+    readonly messageIds: readonly string[]
+}
+
+/** Report returned after cleanup received successful responses for its selected batches.
+ * This reports submissions, not a verified number of deleted messages.
+ * Deletion is not atomic and the SDK does not roll back earlier batches.
+ * An empty selection produces a successful report without a delete request
+ *
+ * @category Messages
+ */
+export interface MessageCleanupReport {
+    /** Channel targeted by the preview plan */
+    readonly channelId: string
+    /** Exact IDs copied from the plan, newest first */
+    readonly selectedMessageIds: readonly string[]
+    /** Number of history messages inspected during the earlier preview, not during deletion */
+    readonly scannedCount: number
+    /** Batch requests that received successful HTTP responses, in submission order */
+    readonly submittedBatches: readonly MessageCleanupBatch[]
+}
+
+/** Progress notification for a cleanup batch, not durable evidence of individual deletions.
+ * The onProgress callback runs synchronously and cleanup continues after it fails.
+ * A throw, a rejected asynchronous return or a returned or resolved Err result reaches the client-level onError as a
+ * progress FailureReport, or is logged at Error. A returned Effect is not run and is reported the same way as misuse.
+ * An application that needs the notification for reconciliation should persist it synchronously.
+ * Cancellation or interruption can leave a submitting batch uncertain without a terminal failed notification
+ *
+ * @category Messages
+ */
+export type MessageCleanupProgress =
+    | {
+          /** The batch is about to be attempted, not proof that it was dispatched */
+          readonly state: "submitting"
+          /** Exact planned batch */
+          readonly batch: MessageCleanupBatch
+      }
+    | {
+          /** Fluxer returned a successful HTTP response for this batch, without per-message deletion proof */
+          readonly state: "submitted"
+          /** Batch whose request succeeded */
+          readonly batch: MessageCleanupBatch
+      }
+    | {
+          /** A batch request failed with one of the documented errors, rather than being interrupted */
+          readonly state: "failed"
+          /** Failed or uncertain batch */
+          readonly batch: MessageCleanupBatch
+          /** Safe failure classification without message bodies or application callback errors */
+          readonly failure: MessageCleanupFailureMetadata
+      }
+
+/** Expected batch failure details included in a failed progress notification.
+ * Contains SDK-owned classifications, not message bodies, filter details or raw provider response text
+ *
+ * @category Errors
+ */
+export interface MessageCleanupFailureMetadata {
+    /** Classified cause of the failure, such as invalid input, closure, rejection or deadline expiry */
+    readonly reason: MessageCleanupErrorReason
+    /** What is known about dispatch: Not sent, definitively rejected, or uncertain */
+    readonly outcome: MessageCleanupOutcome
+    /** Known HTTP status, or null when none is available */
+    readonly status: number | null
+    /** Retry delay reported by Fluxer in milliseconds, or null. This does not establish that retrying is safe */
+    readonly retryAfterMs: number | null
+    /** Safe Fluxer rejection classification, or null, excluding raw response text and provider field paths */
+    readonly apiError: ApiErrorDetail | null
+}
+
+/** Settings for cleanup's batch submissions.
+ * One timeoutMs deadline covers the entire cleanup execution, including rate-limit waits between batches.
+ * Preview has its own separate per-call deadline and does not accept onProgress
+ *
+ * @category Messages
+ */
+export interface MessageCleanupOptions extends MessageOperationOptions {
+    /** Observe submitting, submitted and failed batches synchronously.
+     * Return values are not awaited, and the callback does not schedule retries or recovery.
+     * A throw, a rejected asynchronous return or a returned or resolved Err result goes to the client-level onError as a
+     * progress FailureReport with the thrown, rejected or Err error, or is logged at Error, and cleanup continues.
+     * The callback runs synchronously in both entry points, so a returned Effect is not run. It is reported as a progress
+     * FailureReport with a TypeError instead of being ignored
+     */
+    readonly onProgress?: (progress: MessageCleanupProgress) => unknown
+}
+
+/** Cleanup settings for the Promise and Result API, with AbortSignal cancellation.
+ * Cancellation returns CancelledError rather than a partial report. Earlier requests may already have been submitted.
+ * Use progress observations for application-owned reconciliation. The Effect entry point retains interruption in Cause
+ *
+ * @category Messages
+ */
+export interface DefaultMessageCleanupOptions extends MessageCleanupOptions, OperationOptions {}
+
+/** Expected preview or cleanup failure classification.
+ * The reason filter denotes a bad selection callback, closed denotes client closure, and input denotes invalid settings or plan ownership.
+ * Other values preserve the underlying message operation's failure reason
+ *
+ * @category Errors
+ */
+export type MessageCleanupErrorReason = "filter" | "closed" | "input" | MessageOperationError["reason"]
+
+/** What is known about the failed stage's request.
+ * The outcome notDispatched means no request was sent, rejected means confirmed rejection, and unknown means Fluxer may have acted.
+ * An unknown outcome does not mean it is safe to repeat the request
+ *
+ * @category Messages
+ */
+export type MessageCleanupOutcome = "notDispatched" | "rejected" | "unknown"
+
+/** A cleanup preview or deletion failed, with selected IDs and batch progress where available.
+ * Preview never deletes. Cleanup can fail after earlier batches received successful responses.
+ * The submittedBatches field describes only those earlier responses. The terminalBatchIds field identifies the failed or uncertain request when reached.
+ * Its message and details contain no message bodies or criteria, and it proves neither individual deletion nor safe replay.
+ * A filter that threw keeps its thrown value as cause, and a failed history read or batch request keeps its operation error as cause.
+ * Cancellation in the default API is returned separately as CancelledError. Native interruption and unexpected defects remain outside this error
+ *
+ * @category Errors
+ */
+export class MessageCleanupError extends FluxerlyError {
+    /** Literal error tag for identifying MessageCleanupError */
+    readonly _tag = "MessageCleanupError"
+    /** Which stage failed. The preview phase never deletes, while cleanup can fail after earlier batch submissions */
+    readonly phase: "preview" | "cleanup"
+    /** Expected failure classification. The failed message operation or thrown filter value is available through cause */
+    readonly reason: MessageCleanupErrorReason
+    /** What is known about dispatch at the failed stage, not about the earlier successful batches */
+    readonly outcome: MessageCleanupOutcome
+    /** HTTP status at the failed stage, or null when unavailable */
+    readonly status: number | null
+    /** Fluxer's retry delay in milliseconds, or null. This delay does not establish that a repeat request is safe */
+    readonly retryAfterMs: number | null
+    /** Messages inspected before preview failed, or the completed preview's scan count when cleanup failed */
+    readonly scannedCount: number
+    /** Selected message IDs known at failure time, without message bodies or filter details */
+    readonly selectedMessageIds: readonly string[]
+    /** Earlier batch requests with successful HTTP responses, not confirmed individual deletions */
+    readonly submittedBatches: readonly MessageCleanupBatch[]
+    /** Failed or uncertain batch's IDs when a batch request was reached, otherwise null */
+    readonly terminalBatchIds: readonly string[] | null
+    /** Safe local validation detail, copied and frozen, or null for other failures */
+    readonly inputValidation: InputValidationDetail | null
+    /** Safe Fluxer rejection detail for the failed stage, or null when unavailable */
+    readonly apiError: ApiErrorDetail | null
+    /** Record an expected preview or cleanup failure and the submission knowledge available at that point.
+     * Optional validation and Fluxer details default to null. Construction performs no requests, deletion or recovery
+     */
+    constructor(options: {
+        readonly phase: "preview" | "cleanup"
+        readonly reason: MessageCleanupErrorReason
+        readonly outcome: MessageCleanupOutcome
+        readonly status: number | null
+        readonly retryAfterMs: number | null
+        readonly scannedCount: number
+        readonly selectedMessageIds: readonly string[]
+        readonly submittedBatches: readonly MessageCleanupBatch[]
+        readonly terminalBatchIds: readonly string[] | null
+        readonly inputValidation?: InputValidationDetail | null | undefined
+        readonly apiError?: ApiErrorDetail | null | undefined
+        /**
+         * Fluxer error code that this SDK version does not recognize, recorded as details.providerCode and named in the
+         * message. Ignored when apiError is present or the code does not have the shape of a Fluxer code
+         */
+        readonly providerCode?: string | null | undefined
+        /** Response field path or named check that failed, recorded as details.responseField for reason response */
+        readonly responseField?: string | null | undefined
+        readonly cause?: unknown
+    }) {
+        const phase = options.phase
+        const reason = options.reason
+        const outcome = options.outcome
+        const status = options.status
+        const retryAfterMs = options.retryAfterMs
+        const scannedCount = options.scannedCount
+        const selectedMessageIds = options.selectedMessageIds
+        const submittedBatches = options.submittedBatches
+        const terminalBatchIds = options.terminalBatchIds
+        const inputValidation = options.inputValidation ?? null
+        const apiError = options.apiError ?? null
+        const providerCode = safeProviderCode(apiError, options.providerCode ?? null)
+        const responseField = safeResponseField(options.responseField ?? null)
+        super(
+            operationErrorMessage({
+                subject: "Message cleanup",
+                operation: phase,
+                reason,
+                outcome,
+                status,
+                apiError,
+                inputExplanation: inputValidation?.explanation ?? null,
+                retryAfterMs,
+                facts: { providerCode, responseField },
+            }),
+            {
+                code: `cleanup.${reason}`,
+                hint: operationFailureHint({
+                    reason,
+                    outcome,
+                    status,
+                    retryAfterMs,
+                    apiError,
+                    inputPath: inputValidation?.path ?? null,
+                }),
+                cause: options.cause,
+                details: operationDetails({
+                    phase,
+                    reason,
+                    outcome,
+                    status,
+                    retryAfterMs,
+                    scannedCount,
+                    providerCode,
+                    responseField,
+                }),
+            },
+        )
+        this.phase = phase
+        this.reason = reason
+        this.outcome = outcome
+        this.status = status
+        this.retryAfterMs = retryAfterMs
+        this.scannedCount = scannedCount
+        this.selectedMessageIds = selectedMessageIds
+        this.submittedBatches = submittedBatches
+        this.terminalBatchIds = terminalBatchIds
+        this.apiError = apiError
+        this.name = this._tag
+        this.inputValidation = freezeInputValidationDetail(inputValidation)
+    }
+}
+
+/** Expected preview and cleanup errors shared by both entry points.
+ * CancelledError in the default API and interruption in Effect are separate from this type
+ *
+ * @category Errors
+ */
+export type MessageCleanupFailure = MessageCleanupError