@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/attachments.ts

@@ -0,0 +1,313 @@
+/**
+ * Attachment encoding and projection: Message attachment inputs, their file sources and received attachment metadata.
+ * Invariant: Byte inputs are copied before any wait, while sized files and finite streams stay caller-owned until a transfer
+ * reader is acquired. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { Attachment, AttachmentFileSource, AttachmentStreamSource } from "#sdk/attachments"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { fieldsOnce, identifier, record } from "./decode/primitives.js"
+import { normalizedText } from "./field-text.js"
+
+const attachmentMaxBytes = 52_428_800
+
+export type FileSource =
+    | { readonly kind: "bytes"; readonly data: Uint8Array }
+    | { readonly kind: "file"; readonly file: AttachmentFileSource }
+    | { readonly kind: "stream"; readonly stream: AttachmentStreamSource }
+
+export type FilePart = {
+    id: number
+    filename: string
+    contentType: string
+    size: number
+    source: FileSource
+}
+export type EncodedBody = { json: string; files: FilePart[] }
+
+function filename(value: unknown): value is string {
+    // oxlint-disable-next-line no-control-regex -- rejects control characters in attachment filenames
+    return typeof value === "string" && value.length >= 1 && value.length <= 255 && !/[\x00-\x1f\x7f/\\]/.test(value)
+}
+
+function contentType(value: unknown): value is string {
+    return typeof value === "string" && /^[\x20-\x7e]{1,255}$/.test(value)
+}
+
+function metadata(
+    field: (key: string) => unknown,
+    id: number,
+    values: Record<string, unknown>[],
+): string | InputValidationFailure {
+    const acceptedFilename = field("filename")
+    if (!filename(acceptedFilename))
+        return inputValidationFailure(
+            "attachments[].filename",
+            "format",
+            "Attachment filenames must contain 1 through 255 UTF-16 code units without slashes, backslashes, or control characters",
+        )
+    const providedContentType = field("contentType")
+    if (providedContentType !== undefined && !contentType(providedContentType))
+        return inputValidationFailure(
+            "attachments[].contentType",
+            "format",
+            "Attachment content types must contain 1 through 255 printable ASCII characters",
+        )
+    for (const [key, max] of [
+        ["title", 1024],
+        ["description", 4096],
+    ] as const)
+        if (field(key) !== undefined && !normalizedText(field(key), 1, max))
+            return inputValidationFailure(
+                `attachments[].${key}`,
+                "length",
+                `Attachment ${key} must contain 1 through ${max} UTF-16 code units after Fluxer's normalization`,
+            )
+    const spoiler = field("spoiler")
+    if (spoiler !== undefined && typeof spoiler !== "boolean")
+        return inputValidationFailure("attachments[].spoiler", "type", "Attachment spoiler must be a boolean")
+    values.push({
+        id,
+        filename: acceptedFilename,
+        ...(providedContentType === undefined ? {} : { content_type: providedContentType }),
+        ...(field("title") === undefined ? {} : { title: field("title") }),
+        ...(field("description") === undefined ? {} : { description: field("description") }),
+        flags: spoiler === true ? 8 : 0,
+    })
+    return providedContentType ?? "application/octet-stream"
+}
+
+/** The validated size of a bounded file source, read once with its method checks, or undefined for another value */
+function fileSourceSize(value: unknown): number | undefined {
+    if (!record(value)) return undefined
+    const size = value.size
+    return typeof size === "number" &&
+        Number.isSafeInteger(size) &&
+        size >= 0 &&
+        size <= attachmentMaxBytes &&
+        typeof value.slice === "function" &&
+        typeof value.stream === "function"
+        ? size
+        : undefined
+}
+
+function streamSource(value: unknown): value is AttachmentStreamSource {
+    return record(value) && typeof value.getReader === "function"
+}
+
+/**
+ * Validate attachment structure without reading caller files or streams. Admission later snapshots byte arrays and
+ * reserves exact source sizes. The list is read by index and each attachment field at most once, so the validated
+ * values are the ones sent
+ */
+export function encodeAttachments(value: unknown, edit: boolean) {
+    if (value === undefined) return { metadata: undefined, files: [] as FilePart[], uploadedFilenames: [] as string[] }
+    if (!Array.isArray(value)) return inputValidationFailure("attachments", "type", "Attachments must be an array")
+    const metadataValues: Record<string, unknown>[] = []
+    const files: FilePart[] = []
+    const uploadedFilenames: string[] = []
+    const retained = new Set<string>()
+    const count = value.length
+    for (let index = 0; index < count; index += 1) {
+        const item: unknown = value[index]
+        if (!record(item)) return inputValidationFailure("attachments[]", "type", "Each attachment must be an object")
+        const field = fieldsOnce(item)
+        const retainedId = field("id")
+        if (retainedId !== undefined) {
+            if (!edit)
+                return inputValidationFailure(
+                    "attachments[].id",
+                    "relationship",
+                    "Retained attachment IDs are accepted only when editing a message",
+                )
+            if (!identifier(retainedId))
+                return inputValidationFailure("attachments[].id", "format", "Attachment IDs must be decimal strings")
+            const unsupported = unsupportedKeyFailure(
+                item,
+                ["id", "title", "description"],
+                "attachments[]",
+                "A retained attachment",
+            )
+            if (unsupported) return unsupported
+            if (retained.has(retainedId))
+                return inputValidationFailure("attachments[].id", "unique", "Retained attachment IDs must be unique")
+            for (const [key, max] of [
+                ["title", 1024],
+                ["description", 4096],
+            ] as const)
+                if (field(key) !== undefined && field(key) !== null && !normalizedText(field(key), 1, max))
+                    return inputValidationFailure(
+                        `attachments[].${key}`,
+                        "length",
+                        `Retained attachment ${key} must be null or contain 1 through ${max} UTF-16 code units after Fluxer's normalization`,
+                    )
+            retained.add(retainedId)
+            metadataValues.push({
+                id: retainedId,
+                ...(field("title") === undefined ? {} : { title: field("title") }),
+                ...(field("description") === undefined ? {} : { description: field("description") }),
+            })
+            continue
+        }
+        const id = metadataValues.length
+        let source: FileSource
+        let size: number
+        if (Object.prototype.hasOwnProperty.call(item, "data")) {
+            const unsupported = unsupportedKeyFailure(
+                item,
+                ["data", "filename", "contentType", "title", "description", "spoiler"],
+                "attachments[]",
+                "A byte attachment",
+            )
+            if (unsupported) return unsupported
+            const data = field("data")
+            const buffer = data instanceof Uint8Array ? data.buffer : undefined
+            if (!(data instanceof Uint8Array) || !(buffer instanceof ArrayBuffer))
+                return inputValidationFailure(
+                    "attachments[].data",
+                    "type",
+                    "Attachment data must be an ArrayBuffer-backed Uint8Array",
+                )
+            const byteLength = data.byteLength
+            if (byteLength > attachmentMaxBytes)
+                return inputValidationFailure(
+                    "attachments[].data",
+                    "size",
+                    "Attachment data must not exceed 52,428,800 bytes (50 MiB)",
+                )
+            try {
+                new Uint8Array(buffer, data.byteOffset, byteLength)
+            } catch {
+                // allow-silent: A detached or invalid buffer becomes the typed input failure returned below
+                return inputValidationFailure(
+                    "attachments[].data",
+                    "type",
+                    "Attachment data must reference an accessible ArrayBuffer range",
+                )
+            }
+            source = { kind: "bytes", data }
+            size = byteLength
+        } else if (Object.prototype.hasOwnProperty.call(item, "file")) {
+            const unsupported = unsupportedKeyFailure(
+                item,
+                ["file", "filename", "contentType", "title", "description", "spoiler"],
+                "attachments[]",
+                "A file attachment",
+            )
+            if (unsupported) return unsupported
+            const file = field("file")
+            const fileSize = fileSourceSize(file)
+            if (fileSize === undefined)
+                return inputValidationFailure(
+                    "attachments[].file",
+                    "type",
+                    "Attachment files must be File or Blob objects with slice and stream methods and a size from 0 through 52,428,800 bytes (50 MiB)",
+                )
+            source = { kind: "file", file: file as AttachmentFileSource }
+            size = fileSize
+        } else if (Object.prototype.hasOwnProperty.call(item, "stream")) {
+            const unsupported = unsupportedKeyFailure(
+                item,
+                ["stream", "size", "filename", "contentType", "title", "description", "spoiler"],
+                "attachments[]",
+                "A stream attachment",
+            )
+            if (unsupported) return unsupported
+            const stream = field("stream")
+            if (!streamSource(stream))
+                return inputValidationFailure(
+                    "attachments[].stream",
+                    "type",
+                    "Attachment streams must be ReadableStream objects with a getReader method",
+                )
+            const streamSize = field("size")
+            if (
+                typeof streamSize !== "number" ||
+                !Number.isSafeInteger(streamSize) ||
+                streamSize < 0 ||
+                streamSize > attachmentMaxBytes
+            )
+                return inputValidationFailure(
+                    "attachments[].size",
+                    "range",
+                    "Attachment stream size must be an integer from 0 through 52,428,800 bytes (50 MiB)",
+                )
+            source = { kind: "stream", stream }
+            size = streamSize
+        } else
+            return inputValidationFailure(
+                "attachments[]",
+                "required",
+                "Each new attachment must contain exactly one of data, file, or stream",
+            )
+        const acceptedContentType = metadata(field, id, metadataValues)
+        if (acceptedContentType instanceof InputValidationFailure) return acceptedContentType
+        const acceptedFilename = field("filename") as string
+        uploadedFilenames.push(acceptedFilename)
+        files.push({ id, filename: acceptedFilename, contentType: acceptedContentType, size, source })
+    }
+    return { metadata: metadataValues, files, uploadedFilenames }
+}
+
+export function decodeAttachments(value: unknown): readonly Attachment[] | undefined
+export function decodeAttachments(value: unknown, construct: boolean): readonly Attachment[] | true | undefined
+/** False validates metadata without constructing a projection. The value true is the validation-only success marker */
+export function decodeAttachments(value: unknown, construct = true): readonly Attachment[] | true | undefined {
+    if (value === undefined || value === null) return construct ? Object.freeze([]) : true
+    if (!Array.isArray(value)) return undefined
+    const result: Attachment[] | undefined = construct ? [] : undefined
+    for (const item of value) {
+        if (
+            !record(item) ||
+            !identifier(item.id) ||
+            typeof item.filename !== "string" ||
+            typeof item.size !== "number" ||
+            !Number.isSafeInteger(item.size) ||
+            item.size < 0 ||
+            typeof item.flags !== "number" ||
+            !Number.isSafeInteger(item.flags) ||
+            item.flags < 0
+        )
+            return undefined
+        const out: Record<string, unknown> | undefined = construct
+            ? {
+                  id: item.id,
+                  filename: item.filename,
+                  size: item.size,
+                  flags: item.flags,
+              }
+            : undefined
+        for (const [key, wire] of Object.entries({
+            title: "title",
+            description: "description",
+            contentType: "content_type",
+            contentHash: "content_hash",
+            url: "url",
+            proxyUrl: "proxy_url",
+            placeholder: "placeholder",
+            waveform: "waveform",
+            expiresAt: "expires_at",
+        })) {
+            if (item[wire] == null) continue
+            if (typeof item[wire] !== "string") return undefined
+            if (out) out[key] = item[wire]
+        }
+        for (const key of ["width", "height", "duration"] as const) {
+            if (item[key] == null) continue
+            if (
+                typeof item[key] !== "number" ||
+                !Number.isInteger(item[key]) ||
+                item[key] < -2_147_483_648 ||
+                item[key] > 2_147_483_647
+            )
+                return undefined
+            if (out) out[key] = item[key]
+        }
+        for (const key of ["nsfw", "expired"] as const) {
+            if (item[key] == null) continue
+            if (typeof item[key] !== "boolean") return undefined
+            if (out) out[key] = item[key]
+        }
+        if (out) result!.push(Object.freeze(out) as unknown as Attachment)
+    }
+    return result ? Object.freeze(result) : true
+}

package/src/internal/audit-logs.ts

@@ -0,0 +1,336 @@
+/**
+ * Audit-log reads: Page queries and the projection of audit entries, including gateway audit entries.
+ * Invariant: Reasons, options and changes are projected as provider data and never used as safe diagnostic text.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type {
+    AuditLogActionType,
+    AuditLogChange,
+    AuditLogChangeValue,
+    AuditLogEntry,
+    AuditLogOptions,
+    AuditLogPage,
+    AuditLogPermissionsDiff,
+    AuditLogWebhook,
+} from "#sdk/audit-logs"
+import { AuditLogActions } from "#sdk/audit-logs"
+import type { ForumTag } from "#sdk/channels"
+import { decodeForumDefaultReaction, decodeForumTag, decodeThread } from "./channel-decode.js"
+import { decodeUser } from "./users.js"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import type { GuildRequest } from "./guilds.js"
+import { count as nonNegativeInt32, identifier, record } from "./decode/primitives.js"
+import { rejectCheck } from "./decode/trace.js"
+
+/** Filters accept only known actions, while entries keep any action number, including one Fluxer adds later */
+const actionTypes = new Set<number>(Object.values(AuditLogActions))
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value)
+const actionType = (value: unknown): value is AuditLogActionType => typeof value === "number" && actionTypes.has(value)
+const nullableIdentifier = (value: unknown): value is string | null => value === null || identifier(value)
+const nullableText = (value: unknown): value is string | null => value === null || typeof value === "string"
+
+function changeValue(value: unknown): AuditLogChangeValue | undefined {
+    if (typeof value === "string" || typeof value === "boolean" || value === null) return value
+    if (typeof value === "number") return Number.isFinite(value) ? value : undefined
+    if (Array.isArray(value)) {
+        if (value.every((item) => typeof item === "string")) return Object.freeze([...value] as string[])
+        if (value.every((item) => typeof item === "number" && Number.isFinite(item)))
+            return Object.freeze([...value] as number[])
+        // A forum or media channel change records available_tags as tag objects
+        const tags: ForumTag[] = []
+        for (const item of value) {
+            const tag = decodeForumTag(item)
+            if (!tag) return undefined
+            tags.push(tag)
+        }
+        return Object.freeze(tags)
+    }
+    if (!record(value)) return undefined
+    // A forum or media channel change records default_reaction_emoji as an object of its two emoji fields
+    if ("emoji_id" in value || "emoji_name" in value) return decodeForumDefaultReaction(value)
+    if (!Array.isArray(value.added) || !Array.isArray(value.removed)) return undefined
+    if (
+        !value.added.every((item) => typeof item === "string") ||
+        !value.removed.every((item) => typeof item === "string")
+    )
+        return undefined
+    return Object.freeze({
+        added: Object.freeze([...value.added]),
+        removed: Object.freeze([...value.removed]),
+    }) as AuditLogPermissionsDiff
+}
+
+function changes(value: unknown): readonly AuditLogChange[] | undefined {
+    if (!Array.isArray(value)) return undefined
+    const result: AuditLogChange[] = []
+    for (const item of value) {
+        if (!record(item) || typeof item.key !== "string") return undefined
+        const oldValue = item.old_value === undefined ? undefined : changeValue(item.old_value)
+        const newValue = item.new_value === undefined ? undefined : changeValue(item.new_value)
+        if (
+            (item.old_value !== undefined && oldValue === undefined) ||
+            (item.new_value !== undefined && newValue === undefined)
+        )
+            return undefined
+        result.push(
+            Object.freeze({
+                key: item.key,
+                ...(oldValue === undefined ? {} : { oldValue }),
+                ...(newValue === undefined ? {} : { newValue }),
+            }),
+        )
+    }
+    return Object.freeze(result)
+}
+
+function options(value: unknown): AuditLogOptions | undefined {
+    if (!record(value)) return undefined
+    if (
+        (value.channel_id !== undefined && typeof value.channel_id !== "string") ||
+        (value.count !== undefined && !finite(value.count)) ||
+        (value.delete_member_days !== undefined && typeof value.delete_member_days !== "string") ||
+        (value.delete_message_seconds !== undefined &&
+            (!finite(value.delete_message_seconds) ||
+                !Number.isSafeInteger(Math.round(value.delete_message_seconds * 1000)))) ||
+        (value.id !== undefined && typeof value.id !== "string") ||
+        (value.integration_type !== undefined && !finite(value.integration_type)) ||
+        (value.message_id !== undefined && typeof value.message_id !== "string") ||
+        (value.members_removed !== undefined && !finite(value.members_removed)) ||
+        (value.role_name !== undefined && typeof value.role_name !== "string") ||
+        (value.type !== undefined && !finite(value.type)) ||
+        (value.inviter_id !== undefined && typeof value.inviter_id !== "string") ||
+        (value.max_age !== undefined && !finite(value.max_age)) ||
+        (value.max_uses !== undefined && !finite(value.max_uses)) ||
+        (value.temporary !== undefined && typeof value.temporary !== "boolean") ||
+        (value.uses !== undefined && !finite(value.uses))
+    )
+        return undefined
+    return Object.freeze({
+        ...(value.channel_id === undefined ? {} : { channelId: value.channel_id }),
+        ...(value.count === undefined ? {} : { count: value.count }),
+        ...(value.delete_member_days === undefined ? {} : { deleteMemberDays: value.delete_member_days }),
+        // Fluxer records seconds, and the SDK reports milliseconds like the ban input
+        ...(value.delete_message_seconds === undefined
+            ? {}
+            : { deleteMessagesMs: Math.round((value.delete_message_seconds as number) * 1000) }),
+        ...(value.id === undefined ? {} : { id: value.id }),
+        ...(value.integration_type === undefined ? {} : { integrationType: value.integration_type }),
+        ...(value.message_id === undefined ? {} : { messageId: value.message_id }),
+        ...(value.members_removed === undefined ? {} : { membersRemoved: value.members_removed }),
+        ...(value.role_name === undefined ? {} : { roleName: value.role_name }),
+        ...(value.type === undefined ? {} : { type: value.type }),
+        ...(value.inviter_id === undefined ? {} : { inviterId: value.inviter_id }),
+        ...(value.max_age === undefined ? {} : { maxAgeSeconds: value.max_age }),
+        ...(value.max_uses === undefined ? {} : { maxUses: value.max_uses }),
+        ...(value.temporary === undefined ? {} : { temporary: value.temporary }),
+        ...(value.uses === undefined ? {} : { uses: value.uses }),
+    })
+}
+
+function entry(value: unknown): AuditLogEntry | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        !nonNegativeInt32(value.action_type) ||
+        (value.user_id !== undefined && !nullableIdentifier(value.user_id)) ||
+        (value.target_id !== undefined && !nullableText(value.target_id)) ||
+        (value.reason !== undefined && typeof value.reason !== "string")
+    )
+        return undefined
+    const itemOptions = value.options === undefined ? undefined : options(value.options)
+    const itemChanges = value.changes === undefined ? undefined : changes(value.changes)
+    if ((value.options !== undefined && !itemOptions) || (value.changes !== undefined && !itemChanges)) return undefined
+    return Object.freeze({
+        id: value.id,
+        actionType: value.action_type,
+        ...(value.user_id === undefined ? {} : { userId: value.user_id }),
+        ...(value.target_id === undefined ? {} : { targetId: value.target_id }),
+        ...(value.reason === undefined ? {} : { reason: value.reason }),
+        ...(itemOptions === undefined ? {} : { options: itemOptions }),
+        ...(itemChanges === undefined ? {} : { changes: itemChanges }),
+    })
+}
+
+/** REST and gateway audit options share numeric and boolean types, with older string forms normalized here */
+export function decodeAuditLogEntry(value: unknown): AuditLogEntry | undefined {
+    if (!record(value) || value.options === undefined) return entry(value)
+    if (!record(value.options)) return undefined
+    const normalized: Record<string, unknown> = { ...value.options }
+    for (const key of [
+        "count",
+        "delete_message_seconds",
+        "integration_type",
+        "members_removed",
+        "type",
+        "max_age",
+        "max_uses",
+        "uses",
+    ]) {
+        const item = normalized[key]
+        if (typeof item !== "string") continue
+        const parsed = Number(item)
+        if (Number.isNaN(parsed)) delete normalized[key]
+        else normalized[key] = parsed
+    }
+    if (typeof normalized.temporary === "string") {
+        normalized.temporary = normalized.temporary === "true" || normalized.temporary === "1"
+    }
+    if (!normalized.delete_member_days && typeof normalized.delete_message_days === "string")
+        normalized.delete_member_days = normalized.delete_message_days
+    return entry({ ...value, options: normalized })
+}
+
+function webhook(value: unknown): AuditLogWebhook | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        (value.type !== 1 && value.type !== 2) ||
+        (value.guild_id !== undefined && !nullableIdentifier(value.guild_id)) ||
+        (value.channel_id !== undefined && !nullableIdentifier(value.channel_id)) ||
+        typeof value.name !== "string" ||
+        (value.avatar_hash !== undefined && !nullableText(value.avatar_hash))
+    )
+        return undefined
+    return Object.freeze({
+        id: value.id,
+        type: value.type,
+        ...(value.guild_id === undefined ? {} : { guildId: value.guild_id }),
+        ...(value.channel_id === undefined ? {} : { channelId: value.channel_id }),
+        name: value.name,
+        ...(value.avatar_hash === undefined ? {} : { avatarHash: value.avatar_hash }),
+    })
+}
+
+interface EncodedAuditLogQuery {
+    readonly limit: number
+    readonly before?: string
+    readonly after?: string
+    readonly userId?: string
+    readonly actionType?: AuditLogActionType
+    readonly params: URLSearchParams
+}
+
+function encodeQuery(query?: unknown): EncodedAuditLogQuery | InputValidationFailure {
+    const input = query === undefined ? {} : query
+    if (!record(input)) return inputValidationFailure("query", "type", "Audit log query must be an object")
+    const unsupported = unsupportedKeyFailure(
+        input,
+        ["limit", "before", "after", "userId", "actionType"],
+        "query",
+        "an audit log query",
+    )
+    if (unsupported) return unsupported
+    const limit = input.limit === undefined ? 50 : input.limit
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 100)
+        return inputValidationFailure("query.limit", "range", "Audit log limit must be an integer from 1 through 100")
+    if (input.before !== undefined && !identifier(input.before))
+        return inputValidationFailure(
+            "query.before",
+            "format",
+            "Audit log before cursor must be a decimal entry ID string",
+        )
+    if (input.after !== undefined && !identifier(input.after))
+        return inputValidationFailure(
+            "query.after",
+            "format",
+            "Audit log after cursor must be a decimal entry ID string",
+        )
+    if (input.before !== undefined && input.after !== undefined)
+        return inputValidationFailure(
+            "query",
+            "relationship",
+            "Audit log query cannot combine before and after cursors",
+        )
+    if (input.userId !== undefined && !identifier(input.userId))
+        return inputValidationFailure("query.userId", "format", "Audit log user IDs must be decimal strings")
+    if (input.actionType !== undefined && !actionType(input.actionType))
+        return inputValidationFailure(
+            "query.actionType",
+            "allowedValue",
+            "Audit log action type must be a supported action value",
+        )
+    if (input.userId === undefined && input.actionType === undefined)
+        return inputValidationFailure("query", "required", "Audit log query must select userId or actionType")
+    const params = new URLSearchParams({ limit: String(limit) })
+    if (input.before !== undefined) params.set("before", input.before)
+    if (input.after !== undefined) params.set("after", input.after)
+    if (input.userId !== undefined) params.set("user_id", input.userId)
+    if (input.actionType !== undefined) params.set("action_type", String(input.actionType))
+    return {
+        limit,
+        ...(input.before === undefined ? {} : { before: input.before }),
+        ...(input.after === undefined ? {} : { after: input.after }),
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+        ...(input.actionType === undefined ? {} : { actionType: input.actionType }),
+        params,
+    }
+}
+
+function decodeAuditLogPage(value: unknown, query: EncodedAuditLogQuery, guildId: string): AuditLogPage | undefined {
+    if (!record(value) || !Array.isArray(value.audit_log_entries) || value.audit_log_entries.length > query.limit)
+        return undefined
+    // Fluxer lists the threads that thread actions target, and leaves the list out for callers that cannot see threads
+    const threadValues = value.threads === undefined ? [] : value.threads
+    if (!Array.isArray(value.users) || !Array.isArray(value.webhooks) || !Array.isArray(threadValues)) return undefined
+    const entries: AuditLogEntry[] = []
+    let previous = query.before === undefined ? undefined : BigInt(query.before)
+    for (const source of value.audit_log_entries) {
+        const item = entry(source)
+        if (
+            !item ||
+            (query.userId !== undefined && item.userId !== query.userId) ||
+            (query.actionType !== undefined && item.actionType !== query.actionType)
+        )
+            return undefined
+        if (previous !== undefined && BigInt(item.id) >= previous) return rejectCheck("order")
+        previous = BigInt(item.id)
+        entries.push(item)
+    }
+    if (query.after !== undefined && entries.some((item) => BigInt(item.id) <= BigInt(query.after!)))
+        return rejectCheck("order")
+    const users = []
+    const userIds = new Set<string>()
+    for (const source of value.users) {
+        const user = decodeUser(source)
+        if (!user || userIds.has(user.id)) return undefined
+        userIds.add(user.id)
+        users.push(user)
+    }
+    const webhooks = []
+    const webhookIds = new Set<string>()
+    for (const source of value.webhooks) {
+        const item = webhook(source)
+        if (!item || webhookIds.has(item.id)) return undefined
+        webhookIds.add(item.id)
+        webhooks.push(item)
+    }
+    const threads = []
+    const threadIds = new Set<string>()
+    for (const source of threadValues) {
+        const thread = decodeThread(source)
+        if (!thread || thread.guildId !== guildId || threadIds.has(thread.id)) return undefined
+        threadIds.add(thread.id)
+        threads.push(thread)
+    }
+    return Object.freeze({
+        entries: Object.freeze(entries),
+        users: Object.freeze(users),
+        webhooks: Object.freeze(webhooks),
+        threads: Object.freeze(threads),
+    })
+}
+
+/** Builds a remote-only, filtered audit-log page request without cache admission or a provider-side consolidation write */
+export function auditLogPage(guildId: string, query?: unknown): GuildRequest<AuditLogPage> | InputValidationFailure {
+    const encoded = encodeQuery(query)
+    if (!identifier(guildId)) return inputValidationFailure("guildId", "format", "Guild IDs must be decimal strings")
+    if (encoded instanceof InputValidationFailure) return encoded
+    return {
+        guildId,
+        bucket: "guild:audit-logs",
+        path: `/guilds/${guildId}/audit-logs?${encoded.params}`,
+        method: "GET",
+        status: 200,
+        decode: (value) => decodeAuditLogPage(value, encoded, guildId),
+    }
+}

package/src/internal/audit.ts

@@ -0,0 +1,33 @@
+/**
+ * Audit-reason option shared by audited operations.
+ * Invariant: A reason is printable ASCII, trimmed to 1 through 512 characters and sent only as the X-Audit-Log-Reason header.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { InputValidationFailure, inputValidationFailure } from "#sdk/input-validation"
+import { record } from "./decode/primitives.js"
+
+export interface AuditSettings {
+    readonly auditReason?: string
+}
+
+/** Validate one optional provider audit header without retaining or encoding it */
+export function auditSettings(options?: unknown): AuditSettings | InputValidationFailure {
+    if (options !== undefined && !record(options))
+        return inputValidationFailure("options", "type", "Operation options must be an object")
+    const reason = options?.auditReason
+    if (reason === undefined) return {}
+    if (typeof reason !== "string" || !/^[\x20-\x7E]+$/.test(reason))
+        return inputValidationFailure(
+            "options.auditReason",
+            "format",
+            "Audit reason must contain only printable ASCII characters",
+        )
+    const trimmed = reason.trim()
+    if (!trimmed || trimmed.length > 512)
+        return inputValidationFailure(
+            "options.auditReason",
+            "length",
+            "Audit reason must contain 1 through 512 characters after trimming",
+        )
+    return { auditReason: trimmed }
+}