moderator-toolbox-nxg-for-reddit / modules/config/moduleapi

moduleapi¶

Functions¶

convertUsernotesEditorText()¶

convertUsernotesEditorText(text, target): Promise<UsernotesConvertResult>

Defined in: extension/data/modules/config/moduleapi.ts:437

Converts usernotes editor text between its compressed and decompressed representations, preserving any edits (the conversion always starts from the given text, not from the wiki):

decompressing expands the v6 blob into pretty-printed editable JSON
compressing re-deflates a v6 users object into its blob (shown as pretty JSON, since the v6 page is JSON either way)

A no-op (returning the input) when the text is already in the requested representation.

Parameters¶

text¶

string

The current editor text.

target¶

"compressed" | "decompressed"

The representation to convert to.

Returns¶

Promise<UsernotesConvertResult>

formatWikiEditorText()¶

formatWikiEditorText(raw, opts): string

Defined in: extension/data/modules/config/moduleapi.ts:330

Converts raw wiki page text to display-ready editor text: usernotes pages get their v6 blob expanded, and JSON pages are pretty-printed.

Parameters¶

raw¶

string

The raw wiki page content.

opts¶

WikiEditorPageOptions

What kind of page this is.

Returns¶

string

getConfig()¶

getConfig(subreddit, options?): Promise<ToolboxConfig | undefined>

Defined in: extension/data/modules/config/moduleapi.ts:213

Retrieves the toolbox config for a subreddit, using an in-memory cache to avoid redundant API calls.

Parameters¶

subreddit¶

string

The subreddit name to fetch config for.

options?¶

GetConfigOptions = {}

Read options (see GetConfigOptions).

Returns¶

Promise<ToolboxConfig | undefined>

The normalized config object, or undefined if the subreddit has no toolbox wiki page or an error occurred.

getConfigMirrorStatus()¶

getConfigMirrorStatus(subreddit): Promise<ConfigMirrorStatus>

Defined in: extension/data/modules/config/moduleapi.ts:585

Compares the canonical config page against its legacy 6.x mirror so the compatibility UI can tell a moderator when the mirror has fallen behind - most often because a mirror write failed, which is otherwise only visible as a single toast at save time.

Revision dates alone cannot answer this: Reddit records no revision for a write that changes nothing, so a canonical save touching only NXG-only fields - or enabling compatibility, which writes the mirror first and the canonical page second - leaves the mirror legitimately older. An older mirror is therefore only reported stale once its content is confirmed to differ from the mirror this config would produce.

Deliberately computed on demand rather than tracked in a cached flag: clearCache wipes every cache key, and any module’s save calls it, so a stored flag would be erased at random.

Parameters¶

subreddit¶

string

The subreddit to check.

Returns¶

Promise<ConfigMirrorStatus>

getUsernotesEditorView()¶

getUsernotesEditorView(text): UsernotesEditorView

Defined in: extension/data/modules/config/moduleapi.ts:398

Classifies usernotes editor text as compressed, decompressed, or neither.

Parameters¶

text¶

string

The current editor text.

Returns¶

UsernotesEditorView

loadWikiEditorPage()¶

loadWikiEditorPage(subreddit, actualPage, opts): Promise<WikiEditorLoadResult>

Defined in: extension/data/modules/config/moduleapi.ts:350

Reads a wiki page for the config editor and returns display-ready text.

Parameters¶

subreddit¶

string

The subreddit whose wiki page to read.

actualPage¶

string

The resolved wiki page path (e.g. 'toolbox', 'config/automoderator').

opts¶

WikiEditorPageOptions

What kind of page this is.

Returns¶

Promise<WikiEditorLoadResult>

{ok: true, text} with editor-ready text, or {ok: false, kind} where 'empty' means no page / blank content and 'error' means an unexpected read failure.

loadWikiEditorRevision()¶

loadWikiEditorRevision(subreddit, actualPage, revisionId, opts): Promise<WikiEditorLoadResult>

Defined in: extension/data/modules/config/moduleapi.ts:372

Reads one historical revision of a wiki page for the config editor, formatted the same way as loadWikiEditorPage. Used by the editor’s rollback dropdown - saving the loaded text writes it as a new revision.

Parameters¶

subreddit¶

string

The subreddit whose wiki page to read.

actualPage¶

string

The resolved wiki page path.

revisionId¶

string

The revision UUID from the page’s history listing.

opts¶

WikiEditorPageOptions

What kind of page this is.

Returns¶

Promise<WikiEditorLoadResult>

prepareWikiEditorContent()¶

prepareWikiEditorContent(content, opts): Promise<WikiEditorPrepareResult>

Defined in: extension/data/modules/config/moduleapi.ts:483

Validates and converts editor text into the content to write to the wiki, reversing the display transforms of formatWikiEditorText:

AutoModerator YAML passes through verbatim (Reddit validates it server-side).
Expanded v6 usernotes (ver: 6 with users but no blob) get their blob recompressed - readers inflate blob unconditionally, so saving the expanded form would break the page.
Other JSON is validated and minified.

Parameters¶

content¶

string

The editor text.

opts¶

WikiEditorPageOptions

What kind of page this is.

Returns¶

Promise<WikiEditorPrepareResult>

reloadConfigFromWiki()¶

reloadConfigFromWiki(subreddit): Promise<ToolboxConfig | null>

Defined in: extension/data/modules/config/moduleapi.ts:281

Reads the freshest toolbox config straight from the canonical wiki page, bypassing the config cache. Used by config tabs to refresh their state after an external wiki edit. Callers that need to tell a missing page from an unreadable one want tryReloadConfigFromWiki instead.

Parameters¶

subreddit¶

string

The subreddit name (without the r/ prefix).

Returns¶

Promise<ToolboxConfig | null>

The purified and normalized config, or null if there was none to read.

saveToolboxConfig()¶

saveToolboxConfig(subreddit, config, reason, options?): Promise<ConfigSaveResult>

Defined in: extension/data/modules/config/moduleapi.ts:752

Writes a full toolbox config object to a subreddit’s config wiki page(s), with the standard save feedback and cache invalidation. Shared by every module that persists its slice of the config (mod macros, removal reasons, usernote types, domain tags, ban macros).

The write fans out through the wiki layout resolver: the canonical NXG page is written first, then subs with 6.x compatibility on refresh the legacy toolbox mirror (non-fatally - the canonical save already succeeded). The NXG copy is the v2 schema and carries the compat flag; the legacy copy is down-converted to the classic v1 schema (escape()-encoded text fields, limited-HTML fill-in fields, no NXG metadata) so 6.x parses it cleanly.

Concurrent saves for the same subreddit are serialized: the second call awaits the first before writing, preventing a later write from silently discarding changes made by an earlier in-flight write.

Never rejects - failures are reported through the feedback toasts and returned as a ConfigSaveResult, so fire-and-forget callers don’t need their own error handling and a silent background caller can still tell whether the write landed.

Parameters¶

subreddit¶

string

The subreddit whose toolbox config to write.

config¶

ToolboxConfig

The full toolbox config object.

reason¶

string

The wiki revision note.

options?¶

Write options. silent reports progress and failures to the log instead of the feedback toasts, for background writes the moderator did not ask for - where a toast (especially a failure they can do nothing about, such as missing wiki permission) would be noise.

silent?¶

boolean

Returns¶

Promise<ConfigSaveResult>

saveWikiEditorPage()¶

saveWikiEditorPage(subreddit, actualPage, content, note, isAutomod): Promise<WikiEditorSaveResult>

Defined in: extension/data/modules/config/moduleapi.ts:665

Writes already-validated wiki-editor content to the page and clears the config cache on success. Performs no user feedback of its own - the caller decides what to surface from the returned result.

A raw save of the canonical config page also refreshes the legacy 6.x mirror. Without that the mirror is left behind holding the pre-edit config, which 6.x mods would keep reading - and which every reconcile then has to arbitrate against.

Parameters¶

subreddit¶

string

The subreddit whose wiki page to write.

actualPage¶

string

The resolved wiki page path.

content¶

string

The content to save (JSON pages must already be minified/validated by the caller).

note¶

string

The wiki revision note.

isAutomod¶

boolean

Whether the page is AutoModerator YAML (parses AutoMod special_errors on failure).

Returns¶

Promise<WikiEditorSaveResult>

{ok: true} on success (with mirrorWarning when the 6.x mirror could not be refreshed), or {ok: false, automodError, message} where automodError is the purified inline AutoMod error (or null) and message is the toast text the caller should show.

tryGetConfig()¶

tryGetConfig(subreddit, options?): Promise<ConfigReadResult>

Defined in: extension/data/modules/config/moduleapi.ts:122

Retrieves the toolbox config for a subreddit (cached), returning a discriminated result that distinguishes “no config page” from “could not read the config”. Most callers want getConfig; use this only when an unreadable config must be handled differently from a missing one.

Parameters¶

subreddit¶

string

The subreddit name to fetch config for.

options?¶

GetConfigOptions = {}

Read options (see GetConfigOptions).

Returns¶

Promise<ConfigReadResult>

tryReloadConfigFromWiki()¶

tryReloadConfigFromWiki(subreddit): Promise<ConfigReloadResult>

Defined in: extension/data/modules/config/moduleapi.ts:241

Reads the freshest toolbox config straight from the canonical wiki page, bypassing the config cache, and reports why when there is nothing to return. Runs the same legacy-mirror reconcile as getConfig, so a caller can never end up editing a config that differs from the one the rest of toolbox acts on.

Parameters¶

subreddit¶

string

The subreddit name (without the r/ prefix).

Returns¶

Promise<ConfigReloadResult>

Interfaces¶

ConfigMirrorStatus¶

Defined in: extension/data/modules/config/moduleapi.ts:556

Whether a subreddit’s legacy 6.x config mirror is up to date with the canonical page.

Properties¶

canonicalAt?¶

optional canonicalAt?: number

Defined in: extension/data/modules/config/moduleapi.ts:564

Unix timestamp (seconds) of the canonical page’s newest revision, when known.

mirrorAt?¶

optional mirrorAt?: number

Defined in: extension/data/modules/config/moduleapi.ts:566

Unix timestamp (seconds) of the mirror’s newest revision, when known.

state¶

state: "off" | "inSync" | "stale" | "unknown"

Defined in: extension/data/modules/config/moduleapi.ts:562

off - the sub keeps no mirror; inSync - the mirror is at least as new as the canonical page; stale - the canonical page was written more recently, so 6.x mods are reading old settings; unknown - one of the revision listings could not be read.

ConfigSaveResult¶

Defined in: extension/data/modules/config/moduleapi.ts:711

Outcome of a config save. Returned rather than thrown, so fire-and-forget callers keep working unchanged while a caller that needs to know - a background write whose failure nobody would otherwise see - can check.

Properties¶

message?¶

optional message?: string

Defined in: extension/data/modules/config/moduleapi.ts:721

The underlying failure text, for a caller that reports it.

ok¶

ok: boolean

Defined in: extension/data/modules/config/moduleapi.ts:713

Whether the canonical page was written.

reason?¶

optional reason?: "error" | "conflict"

Defined in: extension/data/modules/config/moduleapi.ts:719

Why it was not written. conflict - another moderator’s edit landed first and the write was skipped rather than clobbering it; error - the write failed, most often because the account lacks wiki permission.

GetConfigOptions¶

Defined in: extension/data/modules/config/moduleapi.ts:104

Options controlling a config read.

Properties¶

allowNonModerated?¶

optional allowNonModerated?: boolean

Defined in: extension/data/modules/config/moduleapi.ts:111

Read even when the viewer does not moderate the sub. Off by default so a non-moderated sub reports absent without firing any wiki read. Opt in only for legitimate cross-sub reads (e.g. removal reasons following a getfrom redirect into a sub you don’t moderate).

WikiEditorPageOptions¶

Defined in: extension/data/modules/config/moduleapi.ts:317

Options describing what kind of page the wiki editor is working with.

Properties¶

isAutomod¶

isAutomod: boolean

Defined in: extension/data/modules/config/moduleapi.ts:321

Whether the page is AutoModerator YAML (skips JSON handling entirely).

isUsernotes¶

isUsernotes: boolean

Defined in: extension/data/modules/config/moduleapi.ts:319

Whether the page is the usernotes page (enables blob expansion/compression).

Type Aliases¶

ConfigReadResult¶

ConfigReadResult = { config: ToolboxConfig; status: "ok"; } | { status: "absent"; } | { status: "error"; }

Defined in: extension/data/modules/config/moduleapi.ts:98

The outcome of a config read, distinguishing the three cases callers that care about safety must not conflate:

ok - the config was read and normalized (config is the result).
absent - the subreddit has no toolbox wiki page (a definite “no config”), cached so later reads short-circuit.
error - the read failed (transient network/API error, or unparseable content), so the config is unknown. Not cached: a later read re-attempts.

getConfig collapses absent/error to undefined for the many callers that treat “no config” the same either way; safety-sensitive callers (training-mode capture) use this richer result so they can fail safe on error instead of assuming “no config”.

ConfigReloadResult¶

ConfigReloadResult = { config: ToolboxConfig; status: "ok"; } | { status: "absent"; } | { status: "invalid"; } | { status: "error"; }

Defined in: extension/data/modules/config/moduleapi.ts:227

The outcome of an uncached config reload. Unlike ConfigReadResult this separates invalid (the page exists but is not usable config) from error (the read itself failed), because the config editor reports the two differently and must not open an empty default over either.

UsernotesConvertResult¶

UsernotesConvertResult = { ok: true; text: string; } | { message: string; ok: false; }

Defined in: extension/data/modules/config/moduleapi.ts:419

The result of converting usernotes editor text between representations.

UsernotesEditorView¶

UsernotesEditorView = "compressed" | "decompressed" | null

Defined in: extension/data/modules/config/moduleapi.ts:392

Which representation of the usernotes page the editor text currently is: 'compressed' (v6 JSON with its zlib blob), 'decompressed' (editable JSON with a users object), or null when the text is neither (blank page, placeholder text, malformed JSON, the NXG shard manifest).

WikiEditorLoadResult¶

WikiEditorLoadResult = { ok: true; text: string; } | { kind: "empty" | "error"; ok: false; }

Defined in: extension/data/modules/config/moduleapi.ts:312

The result of loading a wiki page for the config editor.

WikiEditorPrepareResult¶

WikiEditorPrepareResult = { content: string; ok: true; } | { message: string; ok: false; }

Defined in: extension/data/modules/config/moduleapi.ts:467

The result of preparing editor text for saving.

WikiEditorSaveResult¶

WikiEditorSaveResult = { mirrorWarning?: string; ok: true; } | { automodError: string | null; message: string; ok: false; }

Defined in: extension/data/modules/config/moduleapi.ts:645

The outcome of a saveWikiEditorPage call, for the caller to turn into user feedback.