@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/threads.ts

@@ -0,0 +1,274 @@
+import type { ChannelType, GuildPublicThreadChannel, GuildThreadChannel } from "./channels.js"
+import type { Message, MessageBody, MessageCore, MessageInput } from "./messages.js"
+import type { UserIterationQuery } from "./pagination.js"
+
+/** Settings for a new thread in a text or announcement channel, created with threads.create.
+ * Use threads.createFromMessage to start a thread on an existing message, and threads.createPost in a forum or media
+ * channel. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ThreadCreate {
+    /** Thread name, 1–100 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming.
+     * The original string is sent unchanged
+     */
+    readonly name: string
+    /** Thread type, default ChannelType.PublicThread. A private thread is possible only in a text channel. In an
+     * announcement channel Fluxer creates an announcement thread for PublicThread or AnnouncementThread, and rejects
+     * AnnouncementThread in a text channel
+     */
+    readonly type?:
+        typeof ChannelType.PublicThread | typeof ChannelType.PrivateThread | typeof ChannelType.AnnouncementThread
+    /** Inactivity period in minutes after which Fluxer archives the thread, one of the ThreadAutoArchiveMinutes values,
+     * default ThreadAutoArchiveMinutes.ThreeDays
+     */
+    readonly autoArchiveMinutes?: number
+    /** Slowmode delay in seconds, an integer from 0 through 21,600. Omission copies the parent channel's
+     * defaultThreadRateLimitPerUser
+     */
+    readonly rateLimitPerUser?: number
+    /** Whether members who cannot manage threads may add other such members, default true. Accepted only with type
+     * ChannelType.PrivateThread
+     */
+    readonly invitable?: boolean
+}
+
+/** Settings for a public thread started on an existing message with threads.createFromMessage.
+ * The thread takes the message's ID, and a message can start only one thread. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ThreadFromMessageCreate {
+    /** Thread name, 1–100 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming.
+     * The original string is sent unchanged
+     */
+    readonly name: string
+    /** Inactivity period in minutes after which Fluxer archives the thread, one of the ThreadAutoArchiveMinutes values,
+     * default ThreadAutoArchiveMinutes.ThreeDays
+     */
+    readonly autoArchiveMinutes?: number
+    /** Slowmode delay in seconds, an integer from 0 through 21,600. Omission copies the parent channel's
+     * defaultThreadRateLimitPerUser
+     */
+    readonly rateLimitPerUser?: number
+}
+
+/** The first message of a forum or media post: The content, embeds, files and stickers of messages.send, with
+ * allowedMentions and flags. A post's first message cannot reply to another message, and has no nonce or
+ * text-to-speech setting
+ *
+ * @category Channels
+ */
+export type ForumPostMessage = MessageBody & Pick<MessageInput, "allowedMentions" | "flags">
+
+/** A new post in a forum or media channel, created with threads.createPost. Each post is a public thread with its own
+ * first message. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ForumPostCreate {
+    /** Post name, 1–100 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming.
+     * The original string is sent unchanged
+     */
+    readonly name: string
+    /** The post's first message. Its files are uploaded in the same request as multipart form data */
+    readonly message: ForumPostMessage
+    /** IDs of the channel's forum tags to apply, at most 5 decimal strings. A channel with ChannelFlags.RequireTag
+     * needs at least one, and a moderated tag needs Manage Threads
+     */
+    readonly appliedTagIds?: readonly string[]
+    /** Inactivity period in minutes after which Fluxer archives the post, one of the ThreadAutoArchiveMinutes values,
+     * default ThreadAutoArchiveMinutes.ThreeDays
+     */
+    readonly autoArchiveMinutes?: number
+    /** Slowmode delay in seconds, an integer from 0 through 21,600. Omission copies the channel's
+     * defaultThreadRateLimitPerUser
+     */
+    readonly rateLimitPerUser?: number
+}
+
+/** A post created with threads.createPost: Its thread and its first message, both frozen
+ *
+ * @category Channels
+ */
+export interface ForumPost<M extends MessageCore = Message> {
+    /** The post, a public thread whose parentId is the forum or media channel */
+    readonly thread: GuildPublicThreadChannel
+    /** The post's first message, in the thread, using the client's messageFields selection */
+    readonly message: M
+}
+
+/** Change an existing thread or post with threads.edit. Omitted fields stay unchanged, and an empty input or an
+ * unknown key fails locally. Fluxer lets the thread's creator rename it, archive it, lock it and change
+ * autoArchiveMinutes, invitable and appliedTagIds, while unlocking, rateLimitPerUser, pinned and moderated tags need
+ * Manage Threads. In a locked thread every change needs Manage Threads, and an archived thread accepts only a change
+ * that also sets archived to false
+ *
+ * @category Channels
+ */
+export interface ThreadEdit {
+    /** Thread name, 1–100 UTF-16 code units after U+000C and U+202E removal and surrounding-whitespace trimming.
+     * The original string is sent unchanged
+     */
+    readonly name?: string
+    /** Archive the thread with true, or unarchive it with false */
+    readonly archived?: boolean
+    /** Whether only members who can manage threads may act in the thread */
+    readonly locked?: boolean
+    /** Inactivity period in minutes after which Fluxer archives the thread, one of the ThreadAutoArchiveMinutes values.
+     * A change restarts the period at archiveTimestamp
+     */
+    readonly autoArchiveMinutes?: number
+    /** Slowmode delay in seconds, an integer from 0 through 21,600. Zero disables slowmode */
+    readonly rateLimitPerUser?: number
+    /** Whether members who cannot manage threads may add other such members. Fluxer ignores it on threads that are not
+     * private
+     */
+    readonly invitable?: boolean
+    /** Pin a forum or media post with true, or unpin it with false, by setting ChannelFlags.Pinned. A channel holds at
+     * most one pinned post. Fluxer rejects true on any other thread
+     */
+    readonly pinned?: boolean
+    /** Replace the tags of a forum or media post with these tag IDs, at most 5 decimal strings, with [] removing every
+     * tag. Fluxer rejects it on a public thread in a text channel and ignores it on private and announcement threads
+     */
+    readonly appliedTagIds?: readonly string[]
+}
+
+/** Which archived threads threads.fetchArchived lists: Public threads, private threads, or only the private threads
+ * the bot joined
+ *
+ * @category Channels
+ */
+export type ArchivedThreadScope = "public" | "private" | "joinedPrivate"
+
+/** Select one page of archived threads of a channel. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ArchivedThreadQuery {
+    /** Threads to list, default "public". The scopes "private" and "joinedPrivate" work only in a text channel, and
+     * "private" needs Manage Threads
+     */
+    readonly scope?: ArchivedThreadScope
+    /** Start before this cursor, excluding it. For "public" and "private" it is an ISO 8601 timestamp with a timezone,
+     * compared with the archive time. For "joinedPrivate" it is a decimal thread ID. Omit it for the first page
+     */
+    readonly before?: string
+    /** Maximum threads in the page, an integer from 2 through 100, default 50 */
+    readonly limit?: number
+}
+
+/** One frozen page of archived threads. Each thread the bot joined has membership set
+ *
+ * @category Channels
+ */
+export interface ArchivedThreadPage {
+    /** Archived threads in the order Fluxer listed them */
+    readonly threads: readonly GuildThreadChannel[]
+    /** Whether Fluxer may have more threads after this page. Pass the last thread's archiveTimestamp, or its ID for
+     * "joinedPrivate", as before to read the next page
+     */
+    readonly hasMore: boolean
+}
+
+/** Filters and paging for one threads.search request in a text, announcement, forum or media channel.
+ * Fluxer searches an index that can lag behind recent changes. The bot sees public threads, private threads it joined
+ * and, with Manage Threads, every private thread. Unknown keys and invalid values fail locally
+ *
+ * @category Channels
+ */
+export interface ThreadSearchQuery {
+    /** Text to look for in thread names, at most 100 UTF-16 code units. Omit it to match every name */
+    readonly name?: string
+    /** Forum tag IDs to filter by, at most 20 decimal strings. A tag the channel no longer has matches no thread */
+    readonly tagIds?: readonly string[]
+    /** How tagIds match: "match_some" for any tag, "match_all" for every tag. Defaults to the channel's
+     * defaultTagSetting, otherwise "match_some"
+     */
+    readonly tagSetting?: "match_some" | "match_all"
+    /** True for only archived threads, false for only active threads. Omit it for both */
+    readonly archived?: boolean
+    /** Result order, default "last_message_time" */
+    readonly sortBy?: "last_message_time" | "archive_time" | "relevance" | "creation_time"
+    /** Ascending or descending result order, default "desc" */
+    readonly sortOrder?: "asc" | "desc"
+    /** Maximum threads in the page, an integer from 1 through 25, default 25 */
+    readonly limit?: number
+    /** Matching threads to skip, an integer from 0 through 9,975, default 0 */
+    readonly offset?: number
+    /** Include only thread IDs smaller than this decimal ID */
+    readonly maxId?: string
+    /** Include only thread IDs greater than this decimal ID */
+    readonly minId?: string
+}
+
+/** Successful search response while Fluxer still builds the community's search index. Fluxer answers HTTP 202 and starts
+ * building it. Retry later with another explicit search, which the SDK never sends by itself
+ *
+ * @category Channels
+ */
+export interface ThreadSearchIndexingPage {
+    /** True distinguishes this response from a ThreadSearchResultsPage */
+    readonly indexing: true
+}
+
+/** Search results once Fluxer's index can answer. The page and its threads and messages are frozen
+ *
+ * @category Channels
+ */
+export interface ThreadSearchResultsPage<M extends MessageCore = Message> {
+    /** False distinguishes this response from an indexing response */
+    readonly indexing: false
+    /** Matching threads in result order. Each thread the bot joined has membership set */
+    readonly threads: readonly GuildThreadChannel[]
+    /** The first message of each returned post in a forum or media channel, using the client's messageFields selection.
+     * Its channelId is the post's ID, and a post whose first message is gone has none. Empty in other channels
+     */
+    readonly firstMessages: readonly M[]
+    /** Number of matching threads Fluxer reported with this response, which can change between requests */
+    readonly total: number
+    /** Whether more matching threads follow this page, read by raising offset */
+    readonly hasMore: boolean
+}
+
+/** Successful outcome of one threads.search request. Check indexing before reading results
+ *
+ * @category Channels
+ */
+export type ThreadSearchPage<M extends MessageCore = Message> = ThreadSearchIndexingPage | ThreadSearchResultsPage<M>
+
+/** Options for reading one thread member with threads.fetchMember. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ThreadMemberQuery {
+    /** Also read the user's community membership into ThreadMember.member, default false. The member is decoded with the
+     * thread's community, which the SDK takes from the channel cache when the thread is cached there and otherwise reads
+     * with one extra channel request inside the same deadline
+     */
+    readonly withMember?: boolean
+}
+
+/** Select one page of thread members, in ascending user ID order. Unknown keys fail locally
+ *
+ * @category Channels
+ */
+export interface ThreadMemberPageQuery extends ThreadMemberQuery {
+    /** Start with decimal user IDs greater than this ID, excluding it. Omit it for the first page */
+    readonly after?: string
+    /** Maximum members in the page, an integer from 1 through 100, default 100 */
+    readonly limit?: number
+}
+
+/** Limits and starting point for threads.iterateMembers, reading thread members in ascending user ID order.
+ * The pageSize option defaults to 100 with a range of 1 through 100
+ *
+ * @category Channels
+ */
+export interface ThreadMemberIterationQuery extends UserIterationQuery {
+    /** Also read each user's community membership into ThreadMember.member, default false. The thread's community is
+     * resolved once per consumption, from the channel cache or with one extra channel request on the first page
+     */
+    readonly withMember?: boolean
+}

package/src/users.ts

@@ -0,0 +1,237 @@
+import type { ClientClosedError } 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"
+import type { MessageOperationOptions } from "./messages.js"
+import type { Message, MessageCore } from "./messages.js"
+import type { OperationOptions } from "./client.js"
+
+/** Public identity of a Fluxer account, suitable for displaying who sent a message or belongs to a conversation.
+ * This returned data cannot be changed and does not update when the account changes. It excludes private account fields even for users.fetchSelf.
+ * Community nicknames and community-specific profile settings are separate from this account-wide identity
+ *
+ * @category Users and DMs
+ */
+export interface User {
+    /** Decimal account ID */
+    readonly id: string
+    /** Account username, not unique by itself */
+    readonly username: string
+    /** Provider discriminator used with username to distinguish accounts with the same username */
+    readonly discriminator: string
+    /** Account-wide name shown instead of username where supported, or null when unset */
+    readonly displayName: string | null
+    /** Avatar asset hash, not an image URL, or null when no avatar is supplied */
+    readonly avatar: string | null
+    /** Dominant avatar color, or null */
+    readonly avatarColor: number | null
+    /** Whether Fluxer identifies this account as a bot */
+    readonly isBot: boolean
+    /** Whether Fluxer identifies this account as a system user */
+    readonly isSystem: boolean
+    /** Public account flags returned by Fluxer */
+    readonly flags: number
+}
+
+/** Choose whether users.fetchProfile also asks for profile customization in one community.
+ * Omit guildId for the account-wide profile. This request does not list mutual communities or relationships and does not
+ * fetch a GuildMember
+ *
+ * @category Users and DMs
+ */
+export interface UserProfileQuery {
+    /** Decimal guild ID whose profile settings to include when Fluxer supplies them */
+    readonly guildId?: string
+}
+
+/** Displayable biography, pronouns and visual customization from a profile read.
+ * Null can mean either that the value is unset or that Fluxer hid it for privacy. These fields alone cannot distinguish those cases.
+ * Undefined bannerColor means Fluxer did not supply it
+ *
+ * @category Users and DMs
+ */
+export interface UserProfileFields {
+    /** Biography, null when absent or hidden by profile privacy */
+    readonly bio: string | null
+    /** Pronouns, null when absent or hidden by profile privacy */
+    readonly pronouns: string | null
+    /** Banner hash, or null when absent or withheld by Fluxer */
+    readonly banner: string | null
+    /** Account-profile banner color when Fluxer supplies it. Community-specific profiles do not supply this field */
+    readonly bannerColor?: number | null
+    /** Packed profile accent color, or null */
+    readonly accentColor: number | null
+}
+
+/** Result of users.fetchProfile, combining public identity with the profile information Fluxer allowed this caller to see.
+ * Account-wide and community-specific settings remain separate. The frozen result excludes relationships, connections,
+ * timezone and premium details, and does not populate user or member caches
+ *
+ * @category Users and DMs
+ */
+export interface UserProfile {
+    /** Public account identity returned with this profile, without updating the cache */
+    readonly user: User
+    /** Account-wide profile fields the SDK includes */
+    readonly profile: UserProfileFields
+    /** Explicit community-context profile fields, or null when Fluxer did not supply them. Null does not establish membership */
+    readonly guildProfile: UserProfileFields | null
+    /** Whether Fluxer limited this read by profile privacy. Its omitted unrestricted marker becomes false */
+    readonly isLimited: boolean
+}
+
+/** A one-to-one direct message or group conversation outside a community.
+ * Pass id to the messages API to address this conversation. The frozen snapshot describes returned settings and
+ * recipients, not current access or proof that a later message can be delivered
+ *
+ * @category Users and DMs
+ */
+export interface DirectMessageChannel {
+    /** Decimal channel ID, accepted by the existing messages API */
+    readonly id: string
+    /** Explicitly distinguishes one-to-one and group conversations */
+    readonly type: "dm" | "group"
+    /** Public recipient snapshots supplied by Fluxer, not necessarily including the current bot */
+    readonly recipients: readonly User[]
+    /** Group name, or null when absent */
+    readonly name: string | null
+    /** Group icon hash, or null */
+    readonly icon: string | null
+    /** Group owner ID, or null for a one-to-one DM */
+    readonly ownerId: string | null
+    /** Supplied nickname overrides, keyed by decimal user ID */
+    readonly nicknames: Readonly<Record<string, string>>
+    /** Last message ID supplied by Fluxer, or null */
+    readonly lastMessageId: string | null
+}
+
+/** Rename a group conversation, change its icon or nicknames, or transfer its ownership.
+ * Omitted fields remain unchanged. This does not create a group or add recipients. Fluxer enforces membership and
+ * ownership, and an error after dispatch does not prove that earlier changes were rolled back
+ *
+ * @category Users and DMs
+ */
+export interface DirectMessageGroupEdit {
+    /** Group name, or null to clear it. Raw input may contain at most 10,000 UTF-16 code units. For validation,
+     * Fluxer's general-name rules remove U+000C and U+202E, trim surrounding whitespace, strip provider-defined
+     * invisible characters, normalize whitespace and collapse its runs, then require 1–100 UTF-16 code units. The SDK
+     * sends the original string without lowercasing or hyphenating it
+     */
+    readonly name?: string | null
+    /** Image data URI, or null to clear. Fluxer validates the image */
+    readonly icon?: string | null
+    /** Transfer ownership to an existing non-bot recipient. Requires current ownership */
+    readonly ownerId?: string
+    /** Nicknames keyed by user ID. A nickname must be a nonempty raw string and contain at most 32 UTF-16 code units
+     * after U+000C and U+202E removal and surrounding-whitespace trimming. A normalized-empty string is allowed.
+     * The original string is sent unchanged, and null clears a nickname. Non-owners may change only their own
+     */
+    readonly nicknames?: Readonly<Record<string, string | null>> | null
+}
+
+/**
+ * IDs accompanying a private-channel recipient change. No automatic user fetch
+ *
+ * @category Events and collectors
+ */
+export interface DirectMessageRecipientChange {
+    /** Affected private channel */
+    readonly channelId: string
+    /** Added or removed account */
+    readonly userId: string
+}
+
+/** Latest-message lookup results for the selected private channel IDs.
+ * Look in messages for returned IDs and omittedChannelIds for requested IDs missing from the response.
+ * A channel returned with null differs from a channel missing from the response. Neither explains why no message was returned
+ *
+ * @category Users and DMs
+ */
+export interface DirectMessageLatestMessages<M extends MessageCore = Message> {
+    /** Returned entries keyed by requested channel ID. Null is ambiguous and does not prove an empty channel or access denial */
+    readonly messages: Readonly<Record<string, M | null>>
+    /** Requested IDs omitted by Fluxer, in input order. Omission is distinct from a returned null */
+    readonly omittedChannelIds: readonly string[]
+}
+
+/** Request deadline settings shared with message operations.
+ * The timeoutMs option defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured, milliseconds across local queueing, rate waits, retries and transport.
+ * Cleanup is awaited after the deadline and can make completion take longer
+ *
+ * @category Options
+ */
+export interface UserOperationOptions extends MessageOperationOptions {}
+
+/**
+ * Default API operations begin immediately. Abort interrupts only this operation and does not roll back remote changes
+ *
+ * @category Options
+ */
+export interface DefaultUserOperationOptions extends UserOperationOptions, OperationOptions {}
+
+/**
+ * User/private-conversation operation named by safe failure metadata
+ *
+ * @category Errors
+ */
+export type UserOperation =
+    | "users.fetch"
+    | "users.fetchSelf"
+    | "users.fetchProfile"
+    | "users.get"
+    | "directMessages.open"
+    | "directMessages.fetch"
+    | "directMessages.fetchAll"
+    | "directMessages.fetchLatestMessages"
+    | "directMessages.get"
+    | "directMessages.editGroup"
+    | "directMessages.close"
+    | "directMessages.removeRecipient"
+
+/** Expected failure from account reads or private-conversation operations.
+ * Inspect operation to identify the failed step and outcome before repeating a write. Metadata excludes private
+ * input values and upstream bodies. Default API methods return this error in an Err, while Effect methods fail
+ * in the typed error channel
+ *
+ * @category Errors
+ */
+export class UserOperationError extends FluxerlyError {
+    /** Stable failure discriminator */
+    readonly _tag = "UserOperationError"
+    /** Requested operation */
+    readonly operation: UserOperation
+    /** Failure category, described by {@link OperationReason} */
+    readonly reason: OperationReason
+    /** Whether the request may have reached Fluxer, described by {@link OperationOutcome}.
+     * Reconcile an unknown group edit, close or recipient removal before repeating it
+     */
+    readonly outcome: OperationOutcome
+    /** HTTP status when received */
+    readonly status: number | null
+    /** Fluxer's retry delay in milliseconds when available */
+    readonly retryAfterMs: number | null
+    /** Safe classification of why Fluxer rejected the request, or null when the response could not be classified */
+    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<UserOperation>) {
+        const fields = operationErrorFields(options)
+        super(operationErrorText("User", fields), operationErrorSettings("user", 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
+    }
+}
+
+/**
+ * Cancellation in the default API additionally returns CancelledError. Native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type UserOperationFailure = UserOperationError | ClientClosedError