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

moduleapi¶

Functions¶

convertUsernotesEditorText()¶

convertUsernotesEditorText(text, target): UsernotesConvertResult

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

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¶

UsernotesConvertResult

formatWikiEditorText()¶

formatWikiEditorText(raw, opts): string

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

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:226

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:706

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:411

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:363

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:385

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): WikiEditorPrepareResult

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

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¶

WikiEditorPrepareResult

refreshClassicConfigInlineFields()¶

refreshClassicConfigInlineFields(subreddit, reason): Promise<{ ok: true; } | { message: string; ok: false; }>

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

Rewrites the classic toolbox page after an edit to data that 6.x reads inline from it but NXG keeps on dedicated pages (usernote types, domain tags). With the compat mirror on this refreshes the mirror; on legacy-fallback subs the classic page is the only place usernote types are stored, so without this an edit lives only in the local cache. A no-op on NXG-only subs. The down-convert reads both fields through their caches, which the editing save has just updated.

Silent (callers own any feedback) and never throws.

Parameters¶

subreddit¶

string

The subreddit whose classic config page to rewrite.

reason¶

string

The wiki revision note.

Returns¶

Promise<{ ok: true; } | { message: string; ok: false; }>

{ok: true} when written or not needed, otherwise the failure text.

reloadConfigFromWiki()¶

reloadConfigFromWiki(subreddit): Promise<ToolboxConfig | null>

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

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:873

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:786

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:135

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:254

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>

unsyncedClassicEditsWarning()¶

unsyncedClassicEditsWarning(subreddit, field): Promise<string | undefined>

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

Checks whether an edit to an inline field is about to overwrite 6.x changes on the classic page. NXG never adopts 6.x edits to these fields, so on a compat-on sub a 6.x mod’s change survives only until NXG next rewrites the classic page. Must run before the NXG save: it compares the classic page against NXG’s pre-edit data, and against the NXG page’s timestamp before this save bumps it.

Warns only when both the content differs from what NXG would mirror and the classic page is the newer of the two - a mirror left stale by a failed refresh differs too, but is older. Best-effort: any read failure skips the warning.

Returns the warning rather than showing it: feedback is single-slot, so the caller shows it after the save, where the save’s own messages can’t replace it.

Parameters¶

subreddit¶

string

The subreddit about to be edited.

field¶

ClassicInlineField

The inline field the edit touches.

Returns¶

Promise<string | undefined>

The warning text, or undefined when there is nothing to warn about.

Interfaces¶

ConfigMirrorStatus¶

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

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:685

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

mirrorAt?¶

optional mirrorAt?: number

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

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:683

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:832

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:842

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

ok¶

ok: boolean

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

Whether the canonical page was written.

reason?¶

optional reason?: "error" | "conflict"

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

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:117

Options controlling a config read.

Properties¶

allowNonModerated?¶

optional allowNonModerated?: boolean

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

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:330

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

Properties¶

isAutomod¶

isAutomod: boolean

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

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

isUsernotes¶

isUsernotes: boolean

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

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

Type Aliases¶

ClassicInlineField¶

ClassicInlineField = "usernoteColors" | "domainTags"

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

A classic-config field 6.x reads inline but NXG keeps on a dedicated page.

ConfigReadResult¶

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

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

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:240

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:432

The result of converting usernotes editor text between representations.

UsernotesEditorView¶

UsernotesEditorView = "compressed" | "decompressed" | null

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

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:325

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:480

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:766

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