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

moduleapi¶

Functions¶

convertUsernotesEditorText()¶

convertUsernotesEditorText(text, target): Promise<UsernotesConvertResult>

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

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

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

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.

getUsernotesEditorView()¶

getUsernotesEditorView(text): UsernotesEditorView

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

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

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

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

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

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.

Parameters¶

subreddit¶

string

The subreddit name (without the r/ prefix).

Returns¶

Promise<ToolboxConfig | null>

The purified and normalized config, or null if the wiki read failed.

saveToolboxConfig()¶

saveToolboxConfig(subreddit, config, reason): Promise<void>

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

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, so fire-and-forget callers don’t need their own error handling.

Parameters¶

subreddit¶

string

The subreddit whose toolbox config to write.

config¶

ToolboxConfig

The full toolbox config object.

reason¶

string

The wiki revision note.

Returns¶

Promise<void>

saveWikiEditorPage()¶

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

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

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.

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, 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:92

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>

Interfaces¶

GetConfigOptions¶

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

Options controlling a config read.

Properties¶

allowNonModerated?¶

optional allowNonModerated?: boolean

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

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

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

Properties¶

isAutomod¶

isAutomod: boolean

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

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

isUsernotes¶

isUsernotes: boolean

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

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

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”.

UsernotesConvertResult¶

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

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

The result of converting usernotes editor text between representations.

UsernotesEditorView¶

UsernotesEditorView = "compressed" | "decompressed" | null

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

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

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

The result of preparing editor text for saving.

WikiEditorSaveResult¶

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

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

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