@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/builders.ts

@@ -0,0 +1,390 @@
+import type { AttachmentInput } from "./attachments.js"
+import type { EmbedAuthorInput, EmbedFieldInput, EmbedFooterInput, EmbedInput, EmbedMediaInput } from "./embeds.js"
+import type { AllowedMentions, MessageInput, MessageReference } from "./messages.js"
+import { colors, type ColorInput } from "./colors.js"
+import { ConfigurationError } from "./errors.js"
+import { HelperError } from "./helpers.js"
+
+/**
+ * Display settings for one field added with EmbedBuilder.field
+ *
+ * @category Builders and formatting
+ */
+export interface EmbedFieldOptions {
+    /** Request side-by-side display with neighboring inline fields. Omit or use false for a full-width field */
+    readonly inline?: boolean
+}
+
+/**
+ * Assemble an embed by chaining methods, then pass the builder or `build()`'s plain object in a message operation's embeds.
+ * A message operation builds a supplied builder once when it reads its input, so later changes do not affect that operation.
+ * Setters change this builder and return it so calls can be chained. Later setters replace earlier values, while field methods append.
+ * Every build returns a fresh object, including copied author, footer, media and field objects.
+ * The builder reads supported properties by name, including inherited properties and getters that do not appear in normal key lists.
+ * Values that are not objects and unknown own enumerable fields remain for the message operation to validate.
+ * Building sends nothing. Only color and timestamp convert their input, throwing HelperError for input they cannot convert.
+ * The field method throws ConfigurationError for options that are not an object with an optional boolean inline.
+ * Message operations check lengths, URLs and server limits
+ *
+ * @category Builders and formatting
+ */
+export class EmbedBuilder {
+    private titleValue: string | undefined
+    private descriptionValue: string | undefined
+    private urlValue: string | undefined
+    private colorValue: number | undefined
+    private timestampValue: string | undefined
+    private authorValue: EmbedAuthorInput | undefined
+    private footerValue: EmbedFooterInput | undefined
+    private imageValue: EmbedMediaInput | undefined
+    private thumbnailValue: EmbedMediaInput | undefined
+    private readonly fieldValues: EmbedFieldInput[] = []
+
+    /** Replace the title text and return this builder. Message operations enforce the 256-character limit */
+    title(value: string): this {
+        this.titleValue = value
+        return this
+    }
+
+    /** Replace the body text and return this builder. Message operations enforce the 4096-character limit */
+    description(value: string): this {
+        this.descriptionValue = value
+        return this
+    }
+
+    /** Replace the destination opened from the title and return this builder. The URL is not checked or fetched here */
+    url(value: string): this {
+        this.urlValue = value
+        return this
+    }
+
+    /**
+     * Replace the color and return this builder. Accepts any ColorInput, such as `0xff8800`, `"#ff8800"` or `[255, 136, 0]`,
+     * converted with colors.parse. Input that cannot be converted throws HelperError with operation embed.color
+     */
+    color(value: ColorInput): this {
+        try {
+            this.colorValue = colors.parse(value)
+        } catch (error) {
+            throw new HelperError("embed.color", "color", { cause: error })
+        }
+        return this
+    }
+
+    /**
+     * Replace the embed's timestamp and return this builder. Accepts a Date, Unix epoch milliseconds or an ISO 8601
+     * string with a timezone. A Date or number is converted with toISOString, and a string is kept for the message
+     * operation to validate. An invalid Date or a number outside the Date range throws HelperError with operation embed.timestamp
+     */
+    timestamp(value: Date | number | string): this {
+        if (typeof value === "string") {
+            this.timestampValue = value
+            return this
+        }
+        const date = value instanceof Date ? value : new Date(value)
+        if (!Number.isFinite(date.getTime())) throw new HelperError("embed.timestamp", "time")
+        this.timestampValue = date.toISOString()
+        return this
+    }
+
+    /** Replace the author label and optional links, copy the supplied object, then return this builder */
+    author(value: EmbedAuthorInput): this {
+        this.authorValue = copyEmbedAuthor(value)
+        return this
+    }
+
+    /** Replace the footer text and optional icon, copy the supplied object, then return this builder */
+    footer(value: EmbedFooterInput): this {
+        this.footerValue = copyEmbedFooter(value)
+        return this
+    }
+
+    /** Replace the full-size image URL and optional alternative text, copy the object, then return this builder. No image is uploaded or fetched */
+    image(value: EmbedMediaInput): this {
+        this.imageValue = copyEmbedMedia(value)
+        return this
+    }
+
+    /** Replace the small image URL and optional alternative text, copy the object, then return this builder. No image is uploaded or fetched */
+    thumbnail(value: EmbedMediaInput): this {
+        this.thumbnailValue = copyEmbedMedia(value)
+        return this
+    }
+
+    /** Add a named section after existing fields and return this builder.
+     * Set options.inline to true to request side-by-side display. It defaults to false when the message is sent.
+     * Options that are not an object, or an inline value that is not a boolean, throw ConfigurationError
+     */
+    field(name: string, value: string, options?: EmbedFieldOptions): this {
+        // A boolean third argument is the removed field(name, value, inline) form, which would otherwise drop inline
+        if (options !== undefined && (typeof options !== "object" || options === null || Array.isArray(options)))
+            throw new ConfigurationError("embedField", "EmbedBuilder.field options must be an object", {
+                hint: "Pass display settings as an object, such as field(name, value, { inline: true })",
+            })
+        const inline = (options as { readonly inline?: unknown } | undefined)?.inline
+        if (inline !== undefined && typeof inline !== "boolean")
+            throw new ConfigurationError("embedField", "EmbedBuilder.field options.inline must be a boolean", {
+                hint: "Pass display settings as an object, such as field(name, value, { inline: true })",
+            })
+        this.fieldValues.push(inline === undefined ? { name, value } : { name, value, inline })
+        return this
+    }
+
+    /** Add field objects after existing fields in argument order and return this builder. Copies each object, passing no arguments adds nothing */
+    addFields(...values: readonly EmbedFieldInput[]): this {
+        this.fieldValues.push(...values.map(copyEmbedField))
+        return this
+    }
+
+    /**
+     * Return a fresh plain input snapshot for `messages.send`, `messages.reply` or `messages.edit`.
+     * This method performs no URL, length, attachment or provider-limit validation
+     */
+    build(): EmbedInput {
+        return {
+            ...(this.titleValue === undefined ? {} : { title: this.titleValue }),
+            ...(this.descriptionValue === undefined ? {} : { description: this.descriptionValue }),
+            ...(this.urlValue === undefined ? {} : { url: this.urlValue }),
+            ...(this.colorValue === undefined ? {} : { color: this.colorValue }),
+            ...(this.timestampValue === undefined ? {} : { timestamp: this.timestampValue }),
+            ...(this.authorValue === undefined ? {} : { author: copyEmbedAuthor(this.authorValue) }),
+            ...(this.footerValue === undefined ? {} : { footer: copyEmbedFooter(this.footerValue) }),
+            ...(this.imageValue === undefined ? {} : { image: copyEmbedMedia(this.imageValue) }),
+            ...(this.thumbnailValue === undefined ? {} : { thumbnail: copyEmbedMedia(this.thumbnailValue) }),
+            ...(this.fieldValues.length === 0 ? {} : { fields: this.fieldValues.map(copyEmbedField) }),
+        }
+    }
+}
+
+/**
+ * Assemble a message by chaining methods, then send the plain object returned by `build()`.
+ * Methods change the same builder. Content and settings replace earlier values, while embeds, attachments and stickers append.
+ * The builder reads supported properties by name, including inherited properties and getters that do not appear in normal key lists.
+ * Values that are not objects and unknown own enumerable fields remain for the message operation to validate.
+ * Building does not send or validate a message. In TypeScript, select content, an embed, an attachment or a sticker before calling build.
+ * JavaScript can build an empty object, but message operations reject it. The HasBody type parameter tracks whether a body was selected, not whether its content is valid
+ *
+ * @category Builders and formatting
+ */
+export class MessageBuilder<HasBody extends boolean = false> {
+    declare private readonly hasBodyState: HasBody
+    private contentValue: string | undefined
+    private readonly embedValues: EmbedInput[] = []
+    private readonly attachmentValues: AttachmentInput[] = []
+    private readonly stickerValues: string[] = []
+    private allowedMentionsValue: AllowedMentions | undefined
+    private messageReferenceValue: MessageReference | undefined
+    private flagsValue: number | undefined
+
+    /** Start with no content or settings. TypeScript callers must use a body-selection method before build, not choose HasBody themselves */
+    constructor(..._empty: [HasBody] extends [false] ? ([false] extends [HasBody] ? [] : [never]) : [never]) {}
+
+    /** Replace the message text and return this builder, now buildable in TypeScript. Empty or invalid text is still checked by the message operation */
+    content(value: string): MessageBuilder<true> {
+        this.contentValue = value
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Add one embed and return this builder, now buildable in TypeScript.
+     * Copies the embed's nested objects and fields now. Later changes to the supplied embed or EmbedBuilder do not change this message
+     */
+    embed(value: EmbedInput | EmbedBuilder): MessageBuilder<true> {
+        this.embedValues.push(copyEmbed(value instanceof EmbedBuilder ? value.build() : value))
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Add one or more embeds in argument order and return this builder, copying each just as `embed` does. Message operations check the final count */
+    addEmbeds(
+        ...values: readonly [first: EmbedInput | EmbedBuilder, ...rest: (EmbedInput | EmbedBuilder)[]]
+    ): MessageBuilder<true> {
+        this.embedValues.push(
+            ...values.map((value) => copyEmbed(value instanceof EmbedBuilder ? value.build() : value)),
+        )
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /**
+     * Add one attachment, copying its metadata while keeping the original bytes, file or stream source.
+     * Return this builder, now buildable in TypeScript. File, stream and byte references are not copied or read here.
+     * The builder and its outputs retain those references. Sending does not clear the builder, and direct operations own copying or consuming their inputs
+     */
+    attachment(value: AttachmentInput): MessageBuilder<true> {
+        this.attachmentValues.push(copyAttachment(value))
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Add one or more attachments in argument order and return this builder. Metadata is copied, but bytes, file and stream sources stay shared just as with `attachment` */
+    addAttachments(...values: readonly [first: AttachmentInput, ...rest: AttachmentInput[]]): MessageBuilder<true> {
+        this.attachmentValues.push(...values.map(copyAttachment))
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Add a decimal sticker ID after existing stickers and return this builder. The ID and final sticker count are checked when sending */
+    sticker(value: string): MessageBuilder<true> {
+        this.stickerValues.push(value)
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Add one or more decimal sticker IDs in argument order and return this builder. This does not look up or validate the stickers */
+    addStickers(...values: readonly [first: string, ...rest: string[]]): MessageBuilder<true> {
+        this.stickerValues.push(...values)
+        return this as unknown as MessageBuilder<true>
+    }
+
+    /** Replace who may be notified by mention text, copy user/role arrays, and preserve other values for message-operation validation.
+     * If omitted, message operations keep notifications disabled. This method alone neither inserts mention text nor notifies anyone
+     */
+    allowedMentions(value: AllowedMentions): this {
+        this.allowedMentionsValue = copyAllowedMentions(value)
+        return this
+    }
+
+    /** Choose the message to reply to when using `messages.send`, copy its reference, then return this builder. No message is fetched */
+    reference(value: MessageReference): this {
+        this.messageReferenceValue = copyMessageReference(value)
+        return this
+    }
+
+    /** Replace the numeric message flags and return this builder, without validating the value.
+     * Message operations accept only MessageFlags.SuppressEmbeds and MessageFlags.SuppressNotifications and reject other bits before dispatch
+     */
+    flags(value: number): this {
+        this.flagsValue = value
+        return this
+    }
+
+    /**
+     * Return a fresh plain `MessageInput` after selecting content, an embed, an attachment or a sticker.
+     * Before a body is selected, TypeScript rejects the call with an error naming selectContentEmbedAttachmentOrStickerBeforeBuild.
+     * Sending or replying checks empty text, arrays, attachments and server limits, not this method.
+     * JavaScript can call this on an empty builder and receive `{}`, which message operations reject locally
+     */
+    readonly build = (() => {
+        return {
+            ...(this.contentValue === undefined ? {} : { content: this.contentValue }),
+            ...(this.embedValues.length === 0 ? {} : { embeds: this.embedValues.map(copyEmbed) }),
+            ...(this.attachmentValues.length === 0 ? {} : { attachments: this.attachmentValues.map(copyAttachment) }),
+            ...(this.stickerValues.length === 0 ? {} : { stickerIds: [...this.stickerValues] }),
+            ...(this.allowedMentionsValue === undefined
+                ? {}
+                : { allowedMentions: copyAllowedMentions(this.allowedMentionsValue) }),
+            ...(this.messageReferenceValue === undefined
+                ? {}
+                : { messageReference: copyMessageReference(this.messageReferenceValue) }),
+            ...(this.flagsValue === undefined ? {} : { flags: this.flagsValue }),
+        } as MessageInput
+    }) as [HasBody] extends [true]
+        ? [true] extends [HasBody]
+            ? () => MessageInput
+            : MissingMessageBody
+        : MissingMessageBody
+}
+
+/**
+ * The type of MessageBuilder.build before a body is selected. Calling it fails to compile with an error that names the
+ * missing argument selectContentEmbedAttachmentOrStickerBeforeBuild, which states the fix
+ *
+ * @category Builders and formatting
+ */
+export type MissingMessageBody = (selectContentEmbedAttachmentOrStickerBeforeBuild: never) => never
+
+/** Start optional chainable builders for embed and message objects.
+ * Both package entry points return builders immediately, not lazy Effects
+ *
+ * @category Builders and formatting
+ */
+export const builders: Readonly<{
+    /** Return a new empty EmbedBuilder. Call build to get a plain embed object, no message is sent */
+    embed: () => EmbedBuilder
+    /** Return a new empty MessageBuilder. Select content, an embed, an attachment or a sticker before building */
+    message: () => MessageBuilder<false>
+}> = Object.freeze({
+    embed: () => new EmbedBuilder(),
+    message: () => new MessageBuilder(),
+})
+
+function copyEmbed(value: EmbedInput): EmbedInput {
+    const copied = copyStructuralInput(value, [
+        "title",
+        "description",
+        "url",
+        "color",
+        "timestamp",
+        "author",
+        "footer",
+        "image",
+        "thumbnail",
+        "fields",
+    ])
+    if (!structuralRecord(copied)) return copied
+    return {
+        ...copied,
+        ...(copied.author === undefined ? {} : { author: copyEmbedAuthor(copied.author) }),
+        ...(copied.footer === undefined ? {} : { footer: copyEmbedFooter(copied.footer) }),
+        ...(copied.image === undefined ? {} : { image: copyEmbedMedia(copied.image) }),
+        ...(copied.thumbnail === undefined ? {} : { thumbnail: copyEmbedMedia(copied.thumbnail) }),
+        ...(Array.isArray(copied.fields) ? { fields: copied.fields.map(copyEmbedField) } : {}),
+    }
+}
+
+function copyAllowedMentions(value: AllowedMentions): AllowedMentions {
+    const copied = copyStructuralInput(value, ["users", "roles", "everyone", "repliedUser"])
+    if (!structuralRecord(copied)) return copied
+    return {
+        ...copied,
+        ...(Array.isArray(copied.users) ? { users: [...copied.users] } : {}),
+        ...(Array.isArray(copied.roles) ? { roles: [...copied.roles] } : {}),
+    }
+}
+
+function copyEmbedAuthor(value: EmbedAuthorInput): EmbedAuthorInput {
+    return copyStructuralInput(value, ["name", "url", "iconUrl"])
+}
+
+function copyEmbedFooter(value: EmbedFooterInput): EmbedFooterInput {
+    return copyStructuralInput(value, ["text", "iconUrl"])
+}
+
+function copyEmbedMedia(value: EmbedMediaInput): EmbedMediaInput {
+    return copyStructuralInput(value, ["url", "description"])
+}
+
+function copyEmbedField(value: EmbedFieldInput): EmbedFieldInput {
+    return copyStructuralInput(value, ["name", "value", "inline"])
+}
+
+function copyAttachment(value: AttachmentInput): AttachmentInput {
+    return copyStructuralInput(value, [
+        "data",
+        "file",
+        "stream",
+        "size",
+        "filename",
+        "contentType",
+        "title",
+        "description",
+        "spoiler",
+    ])
+}
+
+function copyMessageReference(value: MessageReference): MessageReference {
+    return copyStructuralInput(value, ["id", "channelId"])
+}
+
+/** Copy an object's enumerable own keys and supported properties read from that object.
+ * Other values remain unchanged for the message operation to validate
+ */
+function copyStructuralInput<Value extends object>(value: Value, properties: readonly (keyof Value)[]): Value {
+    if (!structuralRecord(value)) return value
+    const copied = { ...value } as Record<PropertyKey, unknown>
+    for (const property of properties) {
+        if (Object.hasOwn(copied, property)) continue
+        const item = value[property]
+        if (item !== undefined) copied[property] = item
+    }
+    return copied as Value
+}
+
+function structuralRecord(value: unknown): value is object {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/cache.ts

@@ -0,0 +1,190 @@
+import type { CacheKind } from "./client.js"
+import type { Message, MessageCore } from "./messages.js"
+
+/**
+ * One change applied to a client-owned cache, delivered to cache.onChange listeners after it happened.
+ * A change describes the SDK's local copy, not a remote create, update or delete, and carries no snapshot:
+ * Look the entry up with the matching get method when its value matters
+ *
+ * The key identifies the entry within its kind, using decimal IDs:
+ * Messages use `channelId:messageId`, members use `guildId:userId`, and roles, emojis and stickers use `guildId:id`.
+ * Communities, channels, users and direct messages use the resource ID alone. A clear has a null key.
+ * The cache.delete() method accepts the same keys
+ *
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * // A set can replace an entry and a clear releases a whole kind, so track keys rather than counting events
+ * export function trackCachedKeys(client: Client, keys: Map<string, Set<string>>) {
+ *     return client.cache.onChange((change) => {
+ *         const kindKeys = keys.get(change.kind) ?? new Set<string>()
+ *         keys.set(change.kind, kindKeys)
+ *         if (change.op === "clear") kindKeys.clear()
+ *         else if (change.key !== null && change.op === "set") kindKeys.add(change.key)
+ *         else if (change.key !== null) kindKeys.delete(change.key)
+ *     })
+ * }
+ * ```
+ *
+ * @category Caching
+ */
+export interface CacheChange {
+    /** Cache category whose local copy changed */
+    readonly kind: CacheKind
+    /**
+     * What happened to the local copy.
+     * The value set means an entry was stored or replaced, even with identical content.
+     * The value delete means one entry was removed, including removal by cache.delete(), expiry, capacity eviction, an event, a write or a connection gap limited to known communities.
+     * The value clear means every entry of this kind was released at once, as by cache.clear() with or without this kind, shutdown, a connection gap of unknown scope
+     * or an event or write whose effect cannot be narrowed to single entries.
+     * No delete is reported for the entries a clear released
+     */
+    readonly op: "set" | "delete" | "clear"
+    /** Entry key in the format described for this kind, or null for a clear */
+    readonly key: string | null
+}
+
+/**
+ * Bound the work one cache.onChange listener can hold, so a listener that falls behind or never finishes cannot grow memory without limit.
+ * A listener call is unfinished while its returned Promise or Effect is still running. A synchronous listener finishes each
+ * call before the next change, so these bounds never delay or drop its changes.
+ * Invalid values are misuse: The default API throws ConfigurationError, and the native API dies with it
+ *
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * // One call at a time, so asynchronous work sees the changes in the order they were applied
+ * export function saveChangesInOrder(client: Client, save: (key: string | null) => Promise<void>) {
+ *     return client.cache.onChange((change) => save(change.key), { concurrency: 1, maxPendingChanges: 1_000 })
+ * }
+ * ```
+ *
+ * @category Caching
+ */
+export interface CacheObserverOptions {
+    /** Maximum unfinished listener calls, a positive safe integer, default 256.
+     * Later changes wait in the order they were applied until a call finishes
+     */
+    readonly concurrency?: number
+    /** Maximum changes waiting for an unfinished call, a positive safe integer, default 256.
+     * A change that arrives while this many wait drops the oldest waiting change, logs a cache.changesDropped Warn with the
+     * observer's id and how many changes it has dropped, and counts the drop in diagnostics().counters.cacheChangesDropped
+     */
+    readonly maxPendingChanges?: number
+}
+
+/** Set memory-only cache bounds for a resource category such as users, communities (the guilds category) or channels.
+ * The type parameter is the category's snapshot type, which a maxAgeMs callback receives.
+ * Use true or an options object in ClientOptions.cache to enable that category, which is otherwise disabled.
+ * The SDK keeps frozen copies of resources encountered through supported reads and events, not every remote resource.
+ * Fetches still contact Fluxer, writes still execute, and the SDK does no persistence or background refresh.
+ * It preloads nothing, except that a shard resuming a stored session refills enabled community, role and channel caches
+ * through REST unless sharding.refillCaches is false.
+ * When capacity is full, the least recently used snapshot is removed first.
+ * Expired entries, overlapping reads and lost gateway connections can make a lookup miss.
+ * A connection gap clears affected users and direct messages even if the session resumes. Community-scoped snapshots stay
+ * while the session resumes and are cleared when a new session starts, except cached threads, which a completed Resume
+ * clears. Responses started before the gap are not stored.
+ * Shutdown releases the SDK's copies, not copies still held by the application
+ *
+ * @category Caching
+ */
+export interface ResourceCacheSettings<T = unknown> {
+    /** Maximum snapshots kept for this category across the client, as a positive safe integer.
+     * Defaults to 1,000, not a limit per community
+     */
+    readonly maxEntries?: number
+    /** Maximum accounted UTF-8 JSON bytes kept for this category, as a positive safe integer.
+     * Defaults to 4,194,304 (4 MiB), separate from the message-cache byte budget.
+     * Permission bitfields are counted as decimal strings.
+     * Cache keys, runtime overhead and caller-held copies are excluded, so this is not an exact heap or process-memory limit
+     */
+    readonly maxBytes?: number
+    /**
+     * How long to keep each accepted snapshot, in milliseconds, or a synchronous function that chooses that duration.
+     * Use a nonnegative safe integer, zero to skip retention, or null to disable age expiry.
+     * Omitting this setting also disables age expiry
+     *
+     * The function receives the frozen snapshot and must return a duration or null, so it can cache selectively,
+     * for example by returning zero for snapshots of communities or channels the application does not need.
+     * A throw, undefined, Promise, thenable or invalid number removes the older copy and reports a cache failure with the thrown value or an explanation.
+     * That failure goes to the client-level onError option as a cache FailureReport, or is logged at Error with the thrown value when no hook is set.
+     * Event delivery and successful REST results still succeed when the policy fails.
+     * The SDK does not await or cancel invalid promises and thenables
+     *
+     * Each eligible replacement starts a new age, even when values are unchanged.
+     * Local lookups do not renew age, and expiry removes SDK references without fetching a replacement.
+     * Expiry runs without a lookup and can be delayed by an event-loop stall.
+     * Capacity limits can remove a snapshot before its age limit
+     *
+     * Keep the function nonblocking and side-effect-free, since it runs while the SDK accepts an observation.
+     * Changing state captured by the function affects later observations only
+     */
+    readonly maxAgeMs?: number | null | ((resource: T) => number | null)
+}
+
+/**
+ * Bound the message snapshots kept for local lookups in either API style.
+ * Enable the cache in ClientOptions.cache.messages before using these settings.
+ * Eligible fetch, send, reply, edit and history results, plus gateway create and update events, supply snapshots.
+ * Entry and byte limits apply across this client, not separately per channel or community.
+ * Capacity eviction removes the least recently used snapshot first.
+ * An oversized or zero-age replacement removes the older copy without retaining the new one
+ *
+ * A cache hit is a past observation, not proof of current server state or complete channel history
+ *
+ * Connection gaps prevent older responses from refilling affected snapshots, even after resume.
+ * If a newer read or change overlaps a pending response, that response cannot add or renew a snapshot.
+ * It can remove a different saved copy but may leave an identical copy in place
+ *
+ * Channel deletion or visibility loss removes that channel's snapshots, and a thread deletion its thread's snapshots.
+ * Fluxer deletes a text, announcement, forum or media channel's threads with it and sends no thread deletion events,
+ * so that deletion also removes the snapshots of every channel in its community, or without community context, that
+ * the channel cache does not hold, which without the channel cache means all of them.
+ * Batch deletion evicts selected messages after dispatch even on rejection.
+ * These operations also stop older responses from entering the cache, including some pending reads of other resources
+ *
+ * A ban that requests message deletion evicts this author's cached messages across communities because some messages lack community context.
+ * The server deletion job is asynchronous, so later observations do not establish whether the job has finished
+ *
+ * @category Caching
+ */
+export interface MessageCacheSettings<M extends MessageCore = Message> {
+    /** Maximum messages kept across this client, as a positive safe integer.
+     * Defaults to 1,000, not a separate allowance per channel
+     */
+    readonly maxEntries?: number
+    /** Maximum UTF-8 JSON bytes of retained messages with this client's selected fields, as a positive safe integer.
+     * Defaults to 8,388,608 (8 MiB) and excludes runtime overhead and caller-held copies
+     */
+    readonly maxBytes?: number
+    /**
+     * How long to keep each accepted snapshot, in milliseconds, or a synchronous function that chooses that duration.
+     * Use a nonnegative safe integer, zero to skip retention, or null to disable age expiry.
+     * Omitting this setting also disables age expiry
+     *
+     * The function receives the frozen message with this client's selected fields and must return a duration or null.
+     * A throw, undefined, Promise, thenable or invalid number removes the older copy and reports a cache failure with the thrown value or an explanation.
+     * Message delivery and successful REST results still succeed when the policy fails.
+     * The SDK does not await or cancel invalid promises and thenables
+     *
+     * Each eligible replacement starts a new age, even when values are unchanged.
+     * Local lookups change eviction order but do not renew age.
+     * Expiry removes SDK references without a lookup, although event-loop stalls can delay cleanup and garbage collection is not immediate.
+     * Capacity limits can remove a snapshot before its age limit
+     *
+     * Keep the function nonblocking and side-effect-free, since it runs while the SDK accepts an observation.
+     * Changing state captured by the function affects later observations only
+     *
+     * Removing a cache entry does not delete persistent data or securely erase memory
+     */
+    readonly maxAgeMs?: number | null | ((message: M) => number | null)
+}
+
+/** Configure the message cache in either API. An options object enables caching with defaults for omitted settings.
+ * A throwing or invalid maxAgeMs callback is reported to the client-level onError option as a cache FailureReport,
+ * or logged at Error with the thrown value when no hook is set
+ *
+ * @category Caching
+ */
+export interface MessageCacheOptions<M extends MessageCore = Message> extends MessageCacheSettings<M> {}