@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/user-cache.ts

@@ -0,0 +1,294 @@
+/**
+ * Optional user and private-conversation cache with collection and per-resource stale-completion fences.
+ * Invariant: It keeps public snapshots only, bounded per resource, and a stale completion never repopulates invalidated data.
+ * Every applied store, removal and whole-kind clear is recorded to the client's change hub, a replacement counting as one store.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { ResourceCacheSettings } from "#sdk/cache"
+import type { CacheDiagnostic } from "#sdk/client"
+import type { DirectMessageChannel, User } from "#sdk/users"
+import { ExpiryQueue, ExpiryTimer } from "./expiry-queue.js"
+import type { LogicalScheduler } from "./logical-scheduler.js"
+import type { CacheChangeHub } from "./cache-changes.js"
+import { retentionAge } from "./retention-age.js"
+import { cacheStats, readStats } from "./cache.js"
+
+export type UserResources = { users: User; directMessages: DirectMessageChannel }
+type Kind = keyof UserResources
+type Entry = { kind: Kind; value: User | DirectMessageChannel; bytes: number; expires: number | null }
+const targetGuardCapacity = 256
+
+export type UserCacheGuard = {
+    readonly kind: Kind
+    readonly id?: string
+    readonly mutation: boolean
+    readonly replace: boolean
+    readonly collectionEpoch: object
+    readonly targetEpoch: object
+}
+
+/** Optional client-owned public snapshots with collection and per-resource stale-completion fences */
+export class UserCache {
+    #entries = { users: new Map<string, Entry>(), directMessages: new Map<string, Entry>() }
+    #bytes = { users: 0, directMessages: 0 }
+    readonly #stats = { users: cacheStats(), directMessages: cacheStats() }
+    #collectionEpoch = { users: {}, directMessages: {} }
+    #targetEpoch = { users: {}, directMessages: {} }
+    // Keep only the latest active guard per ID, with a conservative collection fence if callers exceed the bound
+    #targets = {
+        users: new Map<string, UserCacheGuard>(),
+        directMessages: new Map<string, UserCacheGuard>(),
+    }
+    #closed = false
+    #expiry = new ExpiryQueue<Entry & { expires: number }>(
+        (entry) => this.#entries[entry.kind].get(entry.value.id) === entry,
+    )
+    #timer: ExpiryTimer
+
+    constructor(
+        private readonly settings: Partial<Record<Kind, Required<ResourceCacheSettings>>>,
+        private readonly now: () => number,
+        logical?: LogicalScheduler,
+        readonly changes?: CacheChangeHub,
+        private readonly report: (error: unknown) => void = () => undefined,
+    ) {
+        this.#timer = new ExpiryTimer(
+            "user cache",
+            now,
+            () => {
+                this.#purge()
+                this.#schedule()
+            },
+            logical,
+        )
+    }
+
+    begin(kind: Kind, options: { id?: string; mutation?: boolean; replace?: boolean } = {}): UserCacheGuard {
+        const mutation = options.mutation === true
+        const replace = options.replace === true
+        const collection = options.id === undefined || replace
+        if (collection) this.#advanceCollection(kind)
+        else {
+            this.#targetEpoch[kind] = {}
+            const targets = this.#targets[kind]
+            if (!targets.has(options.id!) && targets.size >= targetGuardCapacity) this.#advanceCollection(kind)
+        }
+        const guard: UserCacheGuard = {
+            kind,
+            ...(options.id === undefined ? {} : { id: options.id }),
+            mutation,
+            replace,
+            collectionEpoch: this.#collectionEpoch[kind],
+            targetEpoch: this.#targetEpoch[kind],
+        }
+        if (!collection && !this.#closed) this.#targets[kind].set(options.id!, guard)
+        if (mutation) {
+            if (options.id === undefined) this.#clearKind(kind)
+            else this.#remove(kind, options.id)
+            this.#schedule()
+        }
+        return guard
+    }
+
+    complete(guard: UserCacheGuard, values: readonly (User | DirectMessageChannel)[]) {
+        if (this.#closed) {
+            this.#finish(guard)
+            return
+        }
+        if (!this.#current(guard)) {
+            // A stale write can still have changed Fluxer state, so evict only the resource it could affect
+            if (guard.mutation) this.invalidate(guard.kind, guard.id)
+            this.#finish(guard)
+            return
+        }
+        const settings = this.settings[guard.kind]
+        if (guard.mutation) {
+            if (guard.id === undefined) this.#clearKind(guard.kind)
+            else this.#remove(guard.kind, guard.id)
+        } else if (guard.replace) this.#clearKind(guard.kind)
+        if (settings && settings.maxAgeMs !== 0 && settings.maxEntries !== 0) {
+            this.#purge()
+            for (const value of values) this.#observe(guard.kind, value, settings)
+        }
+        this.#finish(guard)
+        this.#schedule()
+    }
+
+    get<K extends Kind>(kind: K, id: string): UserResources[K] | undefined {
+        const entry = this.#peek(kind, id)
+        // A disabled kind holds nothing, so its lookups are not counted
+        if (this.settings[kind]) this.#stats[kind][entry ? "hits" : "misses"]++
+        if (!entry) return undefined
+        this.#entries[kind].delete(id)
+        this.#entries[kind].set(id, entry)
+        return entry.value as UserResources[K]
+    }
+
+    diagnostics(kind: Kind): CacheDiagnostic {
+        this.#purge()
+        this.#schedule()
+        const settings = this.settings[kind]
+        return {
+            configured: settings !== undefined,
+            retainedEntries: this.#entries[kind].size,
+            accountedBytes: this.#bytes[kind],
+            maxEntries: settings?.maxEntries ?? null,
+            maxBytes: settings?.maxBytes ?? null,
+            ...readStats(this.#stats[kind]),
+        }
+    }
+
+    entries<K extends Kind>(kind: K, limit: number): readonly UserResources[K][] {
+        this.#purge()
+        this.#schedule()
+        const entries: UserResources[K][] = []
+        for (const entry of this.#entries[kind].values()) {
+            entries.push(entry.value as UserResources[K])
+            if (entries.length === limit) break
+        }
+        return Object.freeze(entries)
+    }
+
+    /** Release retained account/conversation observations and make reads begun earlier ineligible to restore them */
+    clear() {
+        if (this.#closed) return
+        this.gap()
+    }
+
+    invalidate(kind: Kind, id?: string) {
+        if (this.#closed) return
+        if (id === undefined) {
+            this.#advanceCollection(kind)
+            this.#clearKind(kind)
+        } else {
+            this.#targetEpoch[kind] = {}
+            this.#targets[kind].delete(id)
+            this.#remove(kind, id)
+        }
+        this.#schedule()
+    }
+
+    failed(guard: UserCacheGuard) {
+        if (this.#closed) {
+            this.#finish(guard)
+            return
+        }
+        if (guard.mutation || this.#current(guard)) this.invalidate(guard.kind, guard.id)
+        this.#finish(guard)
+    }
+
+    gap(affects?: (guildId: string | null | undefined) => boolean) {
+        if (!affects || affects(undefined)) {
+            this.#advanceCollection("users")
+            this.#clearKind("users")
+        }
+        if (!affects || affects(null)) {
+            this.#advanceCollection("directMessages")
+            this.#clearKind("directMessages")
+        }
+        this.#schedule()
+    }
+
+    close() {
+        if (this.#closed) return
+        this.#closed = true
+        this.#advanceCollection("users")
+        this.#advanceCollection("directMessages")
+        this.#clearKind("users")
+        this.#clearKind("directMessages")
+        this.#schedule()
+    }
+
+    #advanceCollection(kind: Kind) {
+        this.#collectionEpoch[kind] = {}
+        this.#targets[kind].clear()
+    }
+
+    #current(guard: UserCacheGuard) {
+        if (guard.collectionEpoch !== this.#collectionEpoch[guard.kind]) return false
+        return guard.id === undefined || guard.replace
+            ? guard.targetEpoch === this.#targetEpoch[guard.kind]
+            : this.#targets[guard.kind].get(guard.id) === guard
+    }
+
+    #finish(guard: UserCacheGuard) {
+        if (guard.id !== undefined && !guard.replace && this.#targets[guard.kind].get(guard.id) === guard)
+            this.#targets[guard.kind].delete(guard.id)
+    }
+
+    #peek(kind: Kind, id: string) {
+        const entry = this.#entries[kind].get(id)
+        if (entry && entry.expires !== null && entry.expires <= this.now()) {
+            this.#remove(kind, id)
+            this.#stats[kind].evictions.expiry++
+            return undefined
+        }
+        return entry
+    }
+
+    /** Remove one retained snapshot, reporting the deletion unless the caller replaces it. Returns whether one was removed */
+    #remove(kind: Kind, id: string, notify = true): boolean {
+        const entry = this.#entries[kind].get(id)
+        if (!entry) return false
+        this.#entries[kind].delete(id)
+        this.#bytes[kind] -= entry.bytes
+        if (notify && this.changes?.active) this.changes.record(kind, "delete", id)
+        return true
+    }
+
+    #clearKind(kind: Kind) {
+        const held = this.#entries[kind].size > 0
+        this.#entries[kind].clear()
+        this.#bytes[kind] = 0
+        if (held && this.changes?.active) this.changes.record(kind, "clear", null)
+    }
+
+    #observe(kind: Kind, value: User | DirectMessageChannel, settings: Required<ResourceCacheSettings>) {
+        const resolved = retentionAge(settings.maxAgeMs, value, `${kind} cache`, "snapshot")
+        if (this.#closed) return
+        if ("error" in resolved) {
+            this.#remove(kind, value.id)
+            this.report(resolved.error)
+            return
+        }
+        const age = resolved.age
+        // A replacement reports one set, while an older copy that the new one cannot replace reports a delete
+        const replaced = this.#remove(kind, value.id, false)
+        const bytes = age === 0 ? 0 : Buffer.byteLength(JSON.stringify(value))
+        if (age === 0 || bytes > settings.maxBytes) {
+            if (replaced && this.changes?.active) this.changes.record(kind, "delete", value.id)
+            return
+        }
+        const entries = this.#entries[kind]
+        while (entries.size >= settings.maxEntries || this.#bytes[kind] > settings.maxBytes - bytes) {
+            this.#remove(kind, entries.keys().next().value!)
+            this.#stats[kind].evictions.capacity++
+        }
+        const entry: Entry = {
+            kind,
+            value,
+            bytes,
+            expires: age === null ? null : this.now() + age,
+        }
+        entries.set(value.id, entry)
+        this.#bytes[kind] += bytes
+        if (entry.expires !== null) this.#expiry.push(entry as Entry & { expires: number })
+        if (this.changes?.active) this.changes.record(kind, "set", value.id)
+    }
+
+    #purge() {
+        this.#expiry.purge(this.now(), (entry) => {
+            if (this.#remove(entry.kind, entry.value.id)) this.#stats[entry.kind].evictions.expiry++
+        })
+    }
+
+    #schedule() {
+        if (this.#closed) {
+            this.#timer.cancel()
+            this.#expiry.clear()
+            return
+        }
+        this.#expiry.compact(this.#entries.users.size + this.#entries.directMessages.size)
+        this.#timer.set(this.#expiry.next())
+    }
+}

package/src/internal/users.ts

@@ -0,0 +1,402 @@
+/**
+ * User and private-conversation operations and projections.
+ * Invariant: Projections keep the public-field allowlist shared by explicit reads and complete user observations.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type {
+    DirectMessageChannel,
+    DirectMessageGroupEdit,
+    DirectMessageLatestMessages,
+    User,
+    UserProfile,
+    UserProfileFields,
+    UserProfileQuery,
+} from "#sdk/users"
+import type { MessageCore } from "#sdk/messages"
+import type { MessageDecoder } from "./message-fields.js"
+import { decodeMessage } from "./message.js"
+import { identifier, record, safeInteger as integer } from "./decode/primitives.js"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { channelName, normalizedText } from "./field-text.js"
+
+/** Validated requests executed by the client's shared REST scheduler */
+export interface UserRequest<A> {
+    readonly majorId: string
+    readonly path: string
+    readonly method: "GET" | "POST" | "PATCH" | "DELETE"
+    readonly status: 200 | 204
+    readonly json?: string
+    readonly decode: (value: unknown) => A | undefined
+    readonly resource: "users" | "directMessages"
+    readonly id?: string
+    readonly replace?: boolean
+    readonly verifyType?: "private" | "group"
+    /** Skips all user-cache conflict guards and writes while retaining the shared REST scheduler and retries */
+    readonly noCache?: boolean
+}
+
+type UserValidationResult<A> = UserRequest<A> | InputValidationFailure
+
+const nullableText = (value: unknown): value is string | null => value === null || typeof value === "string"
+const text = (value: unknown, min: number, max: number): value is string =>
+    // oxlint-disable-next-line typescript/no-misused-spread -- length limits count Unicode code points
+    typeof value === "string" && [...value].length >= min && [...value].length <= max
+
+/** Public-field allowlist, shared by explicit reads and complete user observations */
+export function decodeUser(value: unknown): User | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        typeof value.username !== "string" ||
+        typeof value.discriminator !== "string" ||
+        !nullableText(value.global_name) ||
+        !nullableText(value.avatar) ||
+        !(value.avatar_color === null || integer(value.avatar_color)) ||
+        !integer(value.flags) ||
+        (value.bot !== undefined && typeof value.bot !== "boolean") ||
+        (value.system !== undefined && typeof value.system !== "boolean")
+    )
+        return undefined
+    return Object.freeze({
+        id: value.id,
+        username: value.username,
+        discriminator: value.discriminator,
+        displayName: value.global_name,
+        avatar: value.avatar,
+        avatarColor: value.avatar_color,
+        isBot: value.bot === true,
+        isSystem: value.system === true,
+        flags: value.flags,
+    })
+}
+
+export function decodeDirectMessage(value: unknown): DirectMessageChannel | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        (value.type !== 1 && value.type !== 3) ||
+        (value.guild_id !== undefined && value.guild_id !== null) ||
+        (!(value.type === 3 && value.recipients === undefined) && !Array.isArray(value.recipients)) ||
+        (value.name !== undefined && !nullableText(value.name)) ||
+        (value.icon !== undefined && !nullableText(value.icon)) ||
+        (value.owner_id !== undefined && value.owner_id !== null && !identifier(value.owner_id)) ||
+        (value.last_message_id !== undefined && value.last_message_id !== null && !identifier(value.last_message_id))
+    )
+        return undefined
+    const recipients: User[] = []
+    const ids = new Set<string>()
+    for (const input of (value.recipients ?? []) as unknown[]) {
+        const user = decodeUser(input)
+        if (!user || ids.has(user.id)) return undefined
+        ids.add(user.id)
+        recipients.push(user)
+    }
+    const nicknames: Record<string, string> = {}
+    if (value.nicks !== undefined) {
+        if (!record(value.nicks)) return undefined
+        for (const [id, nick] of Object.entries(value.nicks)) {
+            if (!identifier(id) || !text(nick, 1, 32)) return undefined
+            nicknames[id] = nick
+        }
+    }
+    return Object.freeze({
+        id: value.id,
+        type: value.type === 1 ? "dm" : "group",
+        recipients: Object.freeze(recipients),
+        name: value.name ?? null,
+        icon: value.icon ?? null,
+        ownerId: value.owner_id ?? null,
+        lastMessageId: value.last_message_id ?? null,
+        nicknames: Object.freeze(nicknames),
+    }) as DirectMessageChannel
+}
+
+export function userFetch(id: string): UserValidationResult<User> {
+    if (id !== "@me" && !identifier(id))
+        return inputValidationFailure("userId", "format", "User IDs must be decimal strings or @me")
+    return {
+        majorId: id,
+        path: `/users/${id}`,
+        method: "GET",
+        status: 200,
+        resource: "users",
+        ...(id === "@me" ? {} : { id }),
+        decode: (value) => {
+            const user = decodeUser(value)
+            return user && (id === "@me" || user.id === id) ? user : undefined
+        },
+    }
+}
+
+/** Build one explicit profile read with only a caller-selected guild context and no relationship-expansion flags */
+export function userProfile(id: string, query?: UserProfileQuery): UserValidationResult<UserProfile> {
+    if (!identifier(id)) return inputValidationFailure("userId", "format", "User IDs must be decimal strings")
+    if (query !== undefined && !record(query))
+        return inputValidationFailure("query", "type", "User profile query must be an object")
+    const unsupported = record(query)
+        ? unsupportedKeyFailure(query, ["guildId"], "query", "the user profile query")
+        : undefined
+    if (unsupported) return unsupported
+    if (record(query) && query.guildId !== undefined && !identifier(query.guildId))
+        return inputValidationFailure("query.guildId", "format", "Guild IDs must be decimal strings")
+    const guildId = typeof query?.guildId === "string" ? query.guildId : undefined
+    const path = `/users/${id}/profile${guildId === undefined ? "" : `?guild_id=${encodeURIComponent(guildId)}`}`
+    return {
+        majorId: id,
+        path,
+        method: "GET",
+        status: 200,
+        resource: "users",
+        noCache: true,
+        decode: (value) => {
+            if (
+                !record(value) ||
+                !record(value.user) ||
+                !record(value.user_profile) ||
+                (value.profile_limited !== undefined && typeof value.profile_limited !== "boolean")
+            )
+                return undefined
+            const user = decodeUser(value.user)
+            const profile = decodeUserProfileFields(value.user_profile, true)
+            if (!user || user.id !== id || !profile) return undefined
+
+            const member = value.guild_member
+            if (member !== undefined) {
+                if (!record(member)) return undefined
+                if (member.guild_id !== undefined && (!identifier(member.guild_id) || member.guild_id !== guildId))
+                    return undefined
+                if (member.user !== undefined && (!record(member.user) || member.user.id !== id)) return undefined
+            }
+
+            let guildProfile: UserProfileFields | null = null
+            if (value.guild_member_profile !== undefined && value.guild_member_profile !== null) {
+                if (guildId === undefined) return undefined
+                const decodedGuildProfile = decodeUserProfileFields(value.guild_member_profile, false)
+                if (!decodedGuildProfile) return undefined
+                guildProfile = decodedGuildProfile
+            }
+            return Object.freeze({ user, profile, guildProfile, isLimited: value.profile_limited === true })
+        },
+    }
+}
+
+function decodeUserProfileFields(value: unknown, accountProfile: boolean): UserProfileFields | undefined {
+    if (
+        !record(value) ||
+        !nullableText(value.bio) ||
+        !nullableText(value.pronouns) ||
+        !nullableText(value.banner) ||
+        !(value.accent_color === null || integer(value.accent_color))
+    )
+        return undefined
+    let bannerColor: number | null | undefined
+    if (accountProfile && value.banner_color !== undefined) {
+        if (!(value.banner_color === null || integer(value.banner_color))) return undefined
+        bannerColor = value.banner_color
+    }
+    const profile: UserProfileFields = {
+        bio: value.bio,
+        pronouns: value.pronouns,
+        banner: value.banner,
+        ...(bannerColor === undefined ? {} : { bannerColor }),
+        accentColor: value.accent_color,
+    }
+    return Object.freeze(profile)
+}
+
+export function directMessageOpen(id: string): UserValidationResult<DirectMessageChannel> {
+    if (!identifier(id)) return inputValidationFailure("userId", "format", "User IDs must be decimal strings")
+    const json = JSON.stringify({ recipient_id: id })
+    if (Buffer.byteLength(json) > 4_194_304)
+        return inputValidationFailure(
+            "userId",
+            "size",
+            "Direct message request must not exceed 4,194,304 encoded bytes",
+        )
+    return {
+        majorId: "@me",
+        path: "/users/@me/channels",
+        method: "POST",
+        status: 200,
+        resource: "directMessages",
+        json,
+        decode: (value) => {
+            const channel = decodeDirectMessage(value)
+            return channel?.type === "dm" && channel.recipients.some((user) => user.id === id) ? channel : undefined
+        },
+    }
+}
+
+export function directMessageFetch(id: string): UserValidationResult<DirectMessageChannel> {
+    if (!identifier(id)) return inputValidationFailure("channelId", "format", "Channel IDs must be decimal strings")
+    return {
+        majorId: id,
+        id,
+        path: `/channels/${id}`,
+        method: "GET",
+        status: 200,
+        resource: "directMessages",
+        decode: (value) => {
+            const channel = decodeDirectMessage(value)
+            return channel?.id === id ? channel : undefined
+        },
+    }
+}
+
+export function directMessageList(): UserRequest<readonly DirectMessageChannel[]> {
+    return {
+        majorId: "@me",
+        path: "/users/@me/channels",
+        method: "GET",
+        status: 200,
+        resource: "directMessages",
+        replace: true,
+        decode: (value) => {
+            if (!Array.isArray(value)) return undefined
+            const result: DirectMessageChannel[] = []
+            const ids = new Set<string>()
+            for (const item of value) {
+                // Personal notes are not conversations and are deliberately excluded
+                if (record(item) && item.type === 999) continue
+                const channel = decodeDirectMessage(item)
+                if (!channel || ids.has(channel.id)) return undefined
+                ids.add(channel.id)
+                result.push(channel)
+            }
+            return Object.freeze(result)
+        },
+    }
+}
+
+/** Request latest messages only for explicit private-channel IDs, without cache admission or conversation enumeration */
+export function directMessageLatestMessages(ids: readonly string[]): UserValidationResult<DirectMessageLatestMessages>
+export function directMessageLatestMessages<M extends MessageCore>(
+    ids: readonly string[],
+    decode: MessageDecoder<M>,
+): UserValidationResult<DirectMessageLatestMessages<M>>
+export function directMessageLatestMessages(
+    ids: readonly string[],
+    decode: MessageDecoder<MessageCore> = decodeMessage,
+): UserValidationResult<DirectMessageLatestMessages<MessageCore>> {
+    if (!Array.isArray(ids)) return inputValidationFailure("channelIds", "type", "Channel IDs must be an array")
+    const count = ids.length
+    if (count === 0 || count > 100)
+        return inputValidationFailure("channelIds", "length", "Latest-message reads require 1 through 100 channel IDs")
+    // oxlint-disable-next-line unicorn/no-new-array -- preallocates the counted length once, and the loop below assigns every index
+    const channelIds = new Array<string>(count)
+    for (let index = 0; index < count; index++) channelIds[index] = ids[index]
+    if (channelIds.some((id) => !identifier(id)))
+        return inputValidationFailure("channelIds[]", "format", "Channel IDs must be decimal strings")
+    if (new Set(channelIds).size !== channelIds.length)
+        return inputValidationFailure("channelIds", "unique", "Channel IDs must be unique")
+    const json = JSON.stringify({ channels: channelIds })
+    return {
+        majorId: "@me",
+        path: "/users/@me/channels/messages/preload",
+        method: "POST",
+        status: 200,
+        resource: "directMessages",
+        json,
+        noCache: true,
+        decode: (value) => {
+            if (!record(value) || Object.keys(value).some((id) => !channelIds.includes(id))) return undefined
+            const messages: Record<string, MessageCore | null> = {}
+            for (const [id, item] of Object.entries(value)) {
+                if (item === null) {
+                    messages[id] = null
+                    continue
+                }
+                const message = decode(item)
+                if (!message || message.channelId !== id) return undefined
+                messages[id] = message
+            }
+            const omittedChannelIds = channelIds.filter((id) => !(id in messages))
+            return Object.freeze({
+                messages: Object.freeze(messages),
+                omittedChannelIds: Object.freeze(omittedChannelIds),
+            })
+        },
+    }
+}
+
+export function directMessageEdit(
+    id: string,
+    input: DirectMessageGroupEdit,
+): UserValidationResult<DirectMessageChannel> {
+    if (!identifier(id)) return inputValidationFailure("channelId", "format", "Channel IDs must be decimal strings")
+    if (!record(input)) return inputValidationFailure("input", "type", "Group DM input must be an object")
+    if (Object.keys(input).length === 0)
+        return inputValidationFailure("input", "required", "Group DM input must contain at least one field")
+    const unsupported = unsupportedKeyFailure(
+        input,
+        ["name", "icon", "ownerId", "nicknames"],
+        "input",
+        "the group DM input",
+    )
+    if (unsupported) return unsupported
+    if (input.name !== undefined && input.name !== null && !channelName(input.name))
+        return inputValidationFailure(
+            "input",
+            "format",
+            "Group DM name must be null or contain 1 through 100 UTF-16 code units after Fluxer's normalization, and at most 10,000 before it",
+        )
+    if (
+        input.icon !== undefined &&
+        input.icon !== null &&
+        (typeof input.icon !== "string" ||
+            !/^data:image\/[a-zA-Z0-9.+-]+;base64,[A-Za-z0-9+/]+={0,2}$/.test(input.icon))
+    )
+        return inputValidationFailure("input", "format", "Group DM icon must be null or a base64 image data URI")
+    if (input.ownerId !== undefined && !identifier(input.ownerId))
+        return inputValidationFailure("input", "format", "Group DM owner IDs must be decimal strings")
+    if (
+        input.nicknames !== undefined &&
+        input.nicknames !== null &&
+        (!record(input.nicknames) ||
+            Object.entries(input.nicknames).some(
+                ([id, value]) => !identifier(id) || (value !== null && (value === "" || !normalizedText(value, 0, 32))),
+            ))
+    )
+        return inputValidationFailure(
+            "nicknames",
+            "format",
+            "Group DM nicknames must map decimal user IDs to null or nonempty strings of at most 32 UTF-16 code units after Fluxer's normalization",
+        )
+    const json = JSON.stringify({ name: input.name, icon: input.icon, owner_id: input.ownerId, nicks: input.nicknames })
+    if (json === "{}")
+        return inputValidationFailure(
+            "input",
+            "required",
+            "Group DM input must set at least one field to a defined value",
+        )
+    if (Buffer.byteLength(json) > 4_194_304)
+        return inputValidationFailure("input", "size", "Group DM input must not exceed 4,194,304 encoded bytes")
+    const current = directMessageFetch(id)
+    if (current instanceof InputValidationFailure) return current
+    return {
+        ...current,
+        method: "PATCH",
+        json,
+        verifyType: "group",
+        decode: (value) => {
+            const channel = decodeDirectMessage(value)
+            return channel?.id === id && channel.type === "group" ? channel : undefined
+        },
+    }
+}
+
+export function directMessageClose(id: string, recipient?: string): UserValidationResult<void> {
+    if (!identifier(id)) return inputValidationFailure("channelId", "format", "Channel IDs must be decimal strings")
+    if (recipient !== undefined && !identifier(recipient))
+        return inputValidationFailure("recipientId", "format", "Recipient IDs must be decimal strings")
+    return {
+        majorId: id,
+        id,
+        path: `/channels/${id}${recipient === undefined ? "" : `/recipients/${recipient}`}`,
+        method: "DELETE",
+        status: 204,
+        resource: "directMessages",
+        verifyType: recipient === undefined ? "private" : "group",
+        decode: () => undefined,
+    }
+}