@chatwarden/core 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -4
- package/dist/src/audit.d.ts +27 -5
- package/dist/src/audit.d.ts.map +1 -1
- package/dist/src/audit.js +57 -6
- package/dist/src/audit.js.map +1 -1
- package/dist/src/chatwarden.d.ts +183 -11
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +65 -10
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/documents.d.ts +12 -2
- package/dist/src/documents.d.ts.map +1 -1
- package/dist/src/documents.js +56 -34
- package/dist/src/documents.js.map +1 -1
- package/dist/src/events.d.ts +3 -0
- package/dist/src/events.d.ts.map +1 -1
- package/dist/src/events.js.map +1 -1
- package/dist/src/index.d.ts +20 -11
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +11 -6
- package/dist/src/index.js.map +1 -1
- package/dist/src/ladder.d.ts +2 -0
- package/dist/src/ladder.d.ts.map +1 -1
- package/dist/src/ladder.js +1 -1
- package/dist/src/ladder.js.map +1 -1
- package/dist/src/policy.d.ts +129 -0
- package/dist/src/policy.d.ts.map +1 -0
- package/dist/src/policy.js +242 -0
- package/dist/src/policy.js.map +1 -0
- package/dist/src/profile.d.ts +120 -7
- package/dist/src/profile.d.ts.map +1 -1
- package/dist/src/profile.js +295 -7
- package/dist/src/profile.js.map +1 -1
- package/dist/src/reporting.d.ts +127 -0
- package/dist/src/reporting.d.ts.map +1 -0
- package/dist/src/reporting.js +172 -0
- package/dist/src/reporting.js.map +1 -0
- package/dist/src/reports.d.ts +80 -4
- package/dist/src/reports.d.ts.map +1 -1
- package/dist/src/reports.js +120 -6
- package/dist/src/reports.js.map +1 -1
- package/dist/src/staffReports.d.ts +17 -5
- package/dist/src/staffReports.d.ts.map +1 -1
- package/dist/src/staffReports.js +22 -5
- package/dist/src/staffReports.js.map +1 -1
- package/dist/src/staffViews.d.ts +138 -0
- package/dist/src/staffViews.d.ts.map +1 -0
- package/dist/src/staffViews.js +205 -0
- package/dist/src/staffViews.js.map +1 -0
- package/dist/src/team.d.ts +149 -0
- package/dist/src/team.d.ts.map +1 -0
- package/dist/src/team.js +385 -0
- package/dist/src/team.js.map +1 -0
- package/dist/src/types.d.ts +245 -4
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js +5 -0
- package/dist/src/types.js.map +1 -1
- package/package.json +2 -2
- package/src/audit.ts +71 -7
- package/src/chatwarden.ts +245 -20
- package/src/documents.ts +70 -43
- package/src/events.ts +10 -1
- package/src/index.ts +109 -4
- package/src/ladder.ts +1 -1
- package/src/policy.ts +288 -0
- package/src/profile.ts +369 -14
- package/src/reporting.ts +251 -0
- package/src/reports.ts +163 -10
- package/src/staffReports.ts +33 -7
- package/src/staffViews.ts +325 -0
- package/src/team.ts +422 -0
- package/src/types.ts +257 -4
package/src/profile.ts
CHANGED
|
@@ -1,8 +1,23 @@
|
|
|
1
|
-
import { HISTORY_LOOKBACK_MS, LADDER_TABLE } from './ladder.js';
|
|
1
|
+
import { HISTORY_LOOKBACK_MS, LADDER_TABLE, outcomeLabel } from './ladder.js';
|
|
2
2
|
import { MAX_SANCTION_DURATION_MS } from './sanctions.js';
|
|
3
|
-
import type { LadderRow } from './ladder.js';
|
|
3
|
+
import type { LadderRow, LadderStep } from './ladder.js';
|
|
4
4
|
import { CONDUCT_LEVELS } from './types.js';
|
|
5
5
|
import type { ConductLevel } from './types.js';
|
|
6
|
+
import {
|
|
7
|
+
MAX_REASON_RULES,
|
|
8
|
+
MAX_REPORT_REASONS,
|
|
9
|
+
OTHER_REASON_ID,
|
|
10
|
+
REPORT_FLOWS,
|
|
11
|
+
REPORT_GROUP_MAX,
|
|
12
|
+
REPORT_HINT_MAX,
|
|
13
|
+
REPORT_ID_MAX,
|
|
14
|
+
REPORT_LABEL_MAX,
|
|
15
|
+
REPORT_THANKS_MAX,
|
|
16
|
+
fillReporting,
|
|
17
|
+
isReasonId,
|
|
18
|
+
resolveReporting,
|
|
19
|
+
} from './reporting.js';
|
|
20
|
+
import type { ReportingSettings, ResolvedReporting } from './reporting.js';
|
|
6
21
|
|
|
7
22
|
/**
|
|
8
23
|
* A moderation profile is a game's written standard: what each conduct level means, what happens on a first
|
|
@@ -61,7 +76,8 @@ export interface GuidelineTier {
|
|
|
61
76
|
/** The starter Community Rules flavour that goes with the profile. */
|
|
62
77
|
export type RulesFlavour = 'relaxed' | 'standard' | 'strict';
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
/** Everything a moderation profile held in 0.1.1. The two fields added later are on {@link ModerationProfile} and {@link ResolvedProfile}. */
|
|
80
|
+
export interface ModerationProfileBase {
|
|
65
81
|
/** `'relaxed'`, `'standard'`, `'strict'` or your own. */
|
|
66
82
|
id: string;
|
|
67
83
|
/** Shown in the Guide and on the public page. */
|
|
@@ -106,6 +122,53 @@ export interface ModerationProfile {
|
|
|
106
122
|
guidelines: GuidelineTier[];
|
|
107
123
|
}
|
|
108
124
|
|
|
125
|
+
/**
|
|
126
|
+
* A moderation profile as you write it. A profile from 0.1.1 (without `durations` and `customDuration`) is still one: the two
|
|
127
|
+
* fields are optional here and are filled with their defaults wherever the kit reads a profile. What the kit hands back is a
|
|
128
|
+
* {@link ResolvedProfile}, which has both.
|
|
129
|
+
*/
|
|
130
|
+
export interface ModerationProfile extends ModerationProfileBase {
|
|
131
|
+
/**
|
|
132
|
+
* The lengths a moderator is offered, in milliseconds: sorted from the shortest, no repeats, each from 1 up to 365
|
|
133
|
+
* days (at most {@link MAX_DURATIONS} of them). Permanent is always offered, subject to permission, and is never listed.
|
|
134
|
+
* Default {@link DEFAULT_DURATIONS}: 1 hour, 6 hours, 12 hours, 24 hours, 3 days, 7 days and 30 days. Only the offered
|
|
135
|
+
* list: a decision or a sanction may still name any valid length when `customDuration` is true, and the ladder's own
|
|
136
|
+
* lengths are always allowed.
|
|
137
|
+
*/
|
|
138
|
+
durations?: number[];
|
|
139
|
+
/** May a moderator type a length of their own? Default true. When false, only `durations`, permanent and the profile's own lengths are accepted. */
|
|
140
|
+
customDuration?: boolean;
|
|
141
|
+
/**
|
|
142
|
+
* How players report and what they are told: the flow (default one tap, reason optional), the ordered reasons (default
|
|
143
|
+
* grouped and game-style, each mapped to its starter Community Rules) and the thank-you copy. Every field is optional. See
|
|
144
|
+
* {@link ReportingSettings}.
|
|
145
|
+
*/
|
|
146
|
+
reporting?: ReportingSettings;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* What `defineProfile`, `resolveProfile`, `applyPolicyLayer`, `cw.profile` and `cw.policy.get()` return: a validated, deep-frozen
|
|
151
|
+
* profile with `durations` and `customDuration` filled in. It is a {@link ModerationProfile}, so it can be passed wherever one is
|
|
152
|
+
* taken.
|
|
153
|
+
*/
|
|
154
|
+
export interface ResolvedProfile extends ModerationProfileBase {
|
|
155
|
+
/**
|
|
156
|
+
* The lengths a moderator is offered, in milliseconds: sorted from the shortest, no repeats, each from 1 up to 365
|
|
157
|
+
* days (at most {@link MAX_DURATIONS} of them). Permanent is always offered, subject to permission, and is never listed.
|
|
158
|
+
* Default {@link DEFAULT_DURATIONS}: 1 hour, 6 hours, 12 hours, 24 hours, 3 days, 7 days and 30 days. Only the offered
|
|
159
|
+
* list: a decision or a sanction may still name any valid length when `customDuration` is true, and the ladder's own
|
|
160
|
+
* lengths are always allowed.
|
|
161
|
+
*/
|
|
162
|
+
durations: number[];
|
|
163
|
+
/** May a moderator type a length of their own? When false, only `durations`, permanent and the profile's own lengths are accepted. */
|
|
164
|
+
customDuration: boolean;
|
|
165
|
+
/** The reporting settings in force, every field filled in. */
|
|
166
|
+
reporting: ResolvedReporting;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** @deprecated The same as {@link ModerationProfile}, which now has the two fields optional. */
|
|
170
|
+
export type ProfileInput = ModerationProfile;
|
|
171
|
+
|
|
109
172
|
/** Like `Partial`, all the way down. Arrays are replaced, not merged; `null` is a value. */
|
|
110
173
|
export type DeepPartial<T> = T extends readonly unknown[]
|
|
111
174
|
? T
|
|
@@ -119,10 +182,13 @@ export type ProfileOverrides = DeepPartial<ModerationProfile>;
|
|
|
119
182
|
/** A profile that fails validation. `path` names the field (`'profile.firstOffense.banter'`); the message never echoes a value. */
|
|
120
183
|
export class ProfileError extends Error {
|
|
121
184
|
readonly path: string;
|
|
185
|
+
/** The rule that was broken, without the path. Never a value. */
|
|
186
|
+
readonly reason: string;
|
|
122
187
|
constructor(path: string, reason: string) {
|
|
123
188
|
super(`${path} ${reason}`);
|
|
124
189
|
this.name = 'ProfileError';
|
|
125
190
|
this.path = path;
|
|
191
|
+
this.reason = reason;
|
|
126
192
|
}
|
|
127
193
|
}
|
|
128
194
|
|
|
@@ -142,11 +208,17 @@ const TOP_KEYS = [
|
|
|
142
208
|
'rules',
|
|
143
209
|
'areaRules',
|
|
144
210
|
'severeRules',
|
|
211
|
+
'durations',
|
|
212
|
+
'customDuration',
|
|
213
|
+
'reporting',
|
|
145
214
|
'levels',
|
|
146
215
|
'guidelines',
|
|
147
216
|
] as const;
|
|
148
217
|
/** Top-level keys that may be left out (the kit falls back to its defaults). */
|
|
149
|
-
const
|
|
218
|
+
const RULE_LIST_KEYS: readonly string[] = ['areaRules', 'severeRules'];
|
|
219
|
+
const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting'];
|
|
220
|
+
/** The most rule numbers `areaRules` or `severeRules` may list. */
|
|
221
|
+
export const MAX_RULE_LIST = 100;
|
|
150
222
|
const REPEAT_KEYS = ['windowDays', 'notes', 'distinctGames', 'outcome'] as const;
|
|
151
223
|
const PROFANITY_KEYS = ['mode', 'style', 'add', 'remove', 'only', 'languages'] as const;
|
|
152
224
|
const OUTCOME_KEYS = ['kind', 'durationMs'] as const;
|
|
@@ -173,6 +245,12 @@ export const MAX_DURATION_MS = MAX_SANCTION_DURATION_MS;
|
|
|
173
245
|
/** The longest `repeat.windowDays`: the history lookback (90 days), since the record reaches back no further. */
|
|
174
246
|
export const MAX_WINDOW_DAYS = HISTORY_LOOKBACK_MS / DAY;
|
|
175
247
|
|
|
248
|
+
/** The most lengths `durations` may list: a picker with more than this is not a picker. */
|
|
249
|
+
export const MAX_DURATIONS = 50;
|
|
250
|
+
|
|
251
|
+
/** The lengths offered when a profile does not say: 1 hour, 6 hours, 12 hours, 24 hours, 3 days, 7 days and 30 days. */
|
|
252
|
+
export const DEFAULT_DURATIONS: readonly number[] = Object.freeze([HOUR, 6 * HOUR, 12 * HOUR, DAY, 3 * DAY, 7 * DAY, 30 * DAY]);
|
|
253
|
+
|
|
176
254
|
function fail(path: string, reason: string): never {
|
|
177
255
|
throw new ProfileError(path, reason);
|
|
178
256
|
}
|
|
@@ -230,7 +308,9 @@ function wordList(v: unknown, path: string): void {
|
|
|
230
308
|
}
|
|
231
309
|
|
|
232
310
|
function ruleList(v: unknown, path: string): void {
|
|
233
|
-
stringList(v, path)
|
|
311
|
+
const list = stringList(v, path);
|
|
312
|
+
if (list.length > MAX_RULE_LIST) fail(path, `must list at most ${MAX_RULE_LIST} rule numbers`);
|
|
313
|
+
list.forEach((item, i) => {
|
|
234
314
|
if (!positiveInt(item)) fail(`${path}[${i}]`, 'must be a whole rule number from 1');
|
|
235
315
|
});
|
|
236
316
|
}
|
|
@@ -246,6 +326,19 @@ function outcome(v: unknown, path: string): void {
|
|
|
246
326
|
duration(o['durationMs'], `${path}.durationMs`);
|
|
247
327
|
}
|
|
248
328
|
|
|
329
|
+
function validateDurations(v: unknown, path: string): void {
|
|
330
|
+
if (!Array.isArray(v)) return fail(path, 'must be a list of lengths');
|
|
331
|
+
if (v.length > MAX_DURATIONS) fail(path, `must list at most ${MAX_DURATIONS} lengths`);
|
|
332
|
+
v.forEach((item: unknown, i) => {
|
|
333
|
+
if (!positiveInt(item) || item > MAX_DURATION_MS) {
|
|
334
|
+
fail(`${path}[${i}]`, 'must be a whole number of milliseconds above 0 and at most 365 days');
|
|
335
|
+
}
|
|
336
|
+
});
|
|
337
|
+
for (let i = 1; i < v.length; i += 1) {
|
|
338
|
+
if ((v[i] as number) <= (v[i - 1] as number)) fail(path, 'must be sorted from the shortest, with no repeats');
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
|
|
249
342
|
function validateLadder(v: unknown, path: string): void {
|
|
250
343
|
if (!Array.isArray(v) || v.length !== LADDER_ROWS) fail(path, `must have exactly ${LADDER_ROWS} rows, steps 0 to 5`);
|
|
251
344
|
v.forEach((rowValue: unknown, i) => {
|
|
@@ -292,6 +385,58 @@ function validateGuidelines(v: unknown, path: string): void {
|
|
|
292
385
|
}
|
|
293
386
|
}
|
|
294
387
|
|
|
388
|
+
const REPORTING_KEYS = ['flow', 'reasons', 'thanks'] as const;
|
|
389
|
+
const REASON_KEYS = ['id', 'label', 'hint', 'group', 'rules', 'asksNote', 'enabled'] as const;
|
|
390
|
+
const REASON_OPTIONAL: readonly string[] = ['hint', 'group', 'rules', 'asksNote', 'enabled'];
|
|
391
|
+
|
|
392
|
+
/** A line of text of `min` to `max` characters (not blank when `min` is 1). */
|
|
393
|
+
function lineOf(v: unknown, path: string, min: 0 | 1, max: number): void {
|
|
394
|
+
if (typeof v !== 'string' || (min === 1 && v.trim() === '') || v.length > max) {
|
|
395
|
+
fail(path, min === 1 ? `must be text of 1 to ${max} characters` : `must be text of at most ${max} characters`);
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** The `reporting` section, in input shape (every field optional, a reason needing only an id and a label). */
|
|
400
|
+
function validateReporting(v: unknown, path: string): void {
|
|
401
|
+
const rep = obj(v, path, REPORTING_KEYS, REPORTING_KEYS);
|
|
402
|
+
if (Object.hasOwn(rep, 'flow')) oneOf(rep['flow'], `${path}.flow`, REPORT_FLOWS, "must be 'one_tap', 'reason_first' or 'reason_required'");
|
|
403
|
+
if (Object.hasOwn(rep, 'thanks')) lineOf(rep['thanks'], `${path}.thanks`, 1, REPORT_THANKS_MAX);
|
|
404
|
+
if (!Object.hasOwn(rep, 'reasons')) return;
|
|
405
|
+
|
|
406
|
+
const rp = `${path}.reasons`;
|
|
407
|
+
const list = stringList(rep['reasons'], rp);
|
|
408
|
+
if (list.length < 1 || list.length > MAX_REPORT_REASONS) fail(rp, `must list 1 to ${MAX_REPORT_REASONS} reasons`);
|
|
409
|
+
const seen = new Set<string>();
|
|
410
|
+
list.forEach((item: unknown, i) => {
|
|
411
|
+
const ip = `${rp}[${i}]`;
|
|
412
|
+
const reason = obj(item, ip, REASON_KEYS, REASON_OPTIONAL);
|
|
413
|
+
const id = reason['id'];
|
|
414
|
+
if (!isReasonId(id)) {
|
|
415
|
+
fail(`${ip}.id`, `must be a lowercase slug of 1 to ${REPORT_ID_MAX} letters, digits, _ and -, and not 'none'`);
|
|
416
|
+
}
|
|
417
|
+
if (seen.has(id)) fail(`${ip}.id`, 'is used by another reason');
|
|
418
|
+
seen.add(id);
|
|
419
|
+
lineOf(reason['label'], `${ip}.label`, 1, REPORT_LABEL_MAX);
|
|
420
|
+
if (Object.hasOwn(reason, 'hint')) lineOf(reason['hint'], `${ip}.hint`, 0, REPORT_HINT_MAX);
|
|
421
|
+
if (Object.hasOwn(reason, 'group')) lineOf(reason['group'], `${ip}.group`, 0, REPORT_GROUP_MAX);
|
|
422
|
+
if (Object.hasOwn(reason, 'rules')) {
|
|
423
|
+
const rules = stringList(reason['rules'], `${ip}.rules`);
|
|
424
|
+
if (rules.length > MAX_REASON_RULES) fail(`${ip}.rules`, `must list at most ${MAX_REASON_RULES} rule numbers`);
|
|
425
|
+
rules.forEach((n: unknown, j) => {
|
|
426
|
+
if (!positiveInt(n)) fail(`${ip}.rules[${j}]`, 'must be a whole rule number from 1');
|
|
427
|
+
});
|
|
428
|
+
}
|
|
429
|
+
for (const key of ['asksNote', 'enabled'] as const) {
|
|
430
|
+
if (Object.hasOwn(reason, key) && typeof reason[key] !== 'boolean') fail(`${ip}.${key}`, 'must be true or false');
|
|
431
|
+
}
|
|
432
|
+
});
|
|
433
|
+
const on = (r: unknown): boolean => !isPlain(r) || r['enabled'] !== false;
|
|
434
|
+
if (!list.some(on)) fail(rp, 'must have at least one reason switched on');
|
|
435
|
+
const otherAt = list.findIndex((r) => isPlain(r) && r['id'] === OTHER_REASON_ID);
|
|
436
|
+
if (otherAt === -1) fail(rp, `must keep the '${OTHER_REASON_ID}' reason: it can be relabelled but not removed`);
|
|
437
|
+
if (!on(list[otherAt])) fail(`${rp}[${otherAt}].enabled`, `must stay on: '${OTHER_REASON_ID}' is the fallback reason`);
|
|
438
|
+
}
|
|
439
|
+
|
|
295
440
|
/**
|
|
296
441
|
* Check a profile of unknown shape, throwing {@link ProfileError} (with the field path) at the first problem. The
|
|
297
442
|
* message names the field and the rule, never the value, since a value may be chat text.
|
|
@@ -303,7 +448,7 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
|
|
|
303
448
|
text(p['summary'], 'profile.summary');
|
|
304
449
|
text(p['aiContext'], 'profile.aiContext');
|
|
305
450
|
oneOf(p['rules'], 'profile.rules', RULES_FLAVOURS, "must be 'relaxed', 'standard' or 'strict'");
|
|
306
|
-
for (const key of
|
|
451
|
+
for (const key of RULE_LIST_KEYS) if (Object.hasOwn(p, key)) ruleList(p[key], `profile.${key}`);
|
|
307
452
|
|
|
308
453
|
const first = obj(p['firstOffense'], 'profile.firstOffense', CONDUCT_LEVELS);
|
|
309
454
|
for (const level of CONDUCT_LEVELS) outcome(first[level], `profile.firstOffense.${level}`);
|
|
@@ -328,6 +473,11 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
|
|
|
328
473
|
|
|
329
474
|
validateLadder(p['ladder'], 'profile.ladder');
|
|
330
475
|
|
|
476
|
+
// Both are optional (a 0.1.1 profile has neither); when present they are checked.
|
|
477
|
+
if (Object.hasOwn(p, 'durations')) validateDurations(p['durations'], 'profile.durations');
|
|
478
|
+
if (Object.hasOwn(p, 'customDuration') && typeof p['customDuration'] !== 'boolean') fail('profile.customDuration', 'must be true or false');
|
|
479
|
+
if (Object.hasOwn(p, 'reporting')) validateReporting(p['reporting'], 'profile.reporting');
|
|
480
|
+
|
|
331
481
|
const prof = obj(p['profanity'], 'profile.profanity', PROFANITY_KEYS);
|
|
332
482
|
oneOf(prof['mode'], 'profile.profanity.mode', PROFANITY_MODES, "must be 'allow', 'star' or 'refuse'");
|
|
333
483
|
oneOf(prof['style'], 'profile.profanity.style', PROFANITY_STYLES, "must be 'full', 'keepFirst' or 'grawlix'");
|
|
@@ -399,18 +549,54 @@ function deepFreeze<T>(v: T): T {
|
|
|
399
549
|
/** Drop repeated numbers from `areaRules` and `severeRules` (first one wins, order kept) before they are validated. */
|
|
400
550
|
function dedupeRuleLists(copy: unknown): void {
|
|
401
551
|
if (!isPlain(copy)) return;
|
|
402
|
-
for (const key of
|
|
552
|
+
for (const key of RULE_LIST_KEYS) {
|
|
403
553
|
const list = copy[key];
|
|
554
|
+
// Counted before the quadratic de-duplication below, so a huge list is refused without being worked through.
|
|
555
|
+
if (Array.isArray(list) && list.length > MAX_RULE_LIST) fail(`profile.${key}`, `must list at most ${MAX_RULE_LIST} rule numbers`);
|
|
404
556
|
if (Array.isArray(list)) setOwn(copy, key, list.filter((item: unknown, i) => list.findIndex((other: unknown) => Object.is(other, item)) === i));
|
|
405
557
|
}
|
|
406
558
|
}
|
|
407
559
|
|
|
560
|
+
/**
|
|
561
|
+
* Each reason's rule list is counted (a huge one is refused before any work is done) and de-duplicated, as `areaRules` is.
|
|
562
|
+
* Anything that is not the expected shape is left alone for the validator to name.
|
|
563
|
+
*/
|
|
564
|
+
function dedupeReasonRules(copy: Record<string, unknown>): void {
|
|
565
|
+
const reporting = copy['reporting'];
|
|
566
|
+
if (!isPlain(reporting) || !Array.isArray(reporting['reasons']) || reporting['reasons'].length > MAX_REPORT_REASONS) return;
|
|
567
|
+
(reporting['reasons'] as unknown[]).forEach((reason, i) => {
|
|
568
|
+
if (!isPlain(reason) || !Array.isArray(reason['rules'])) return;
|
|
569
|
+
const rules = reason['rules'] as unknown[];
|
|
570
|
+
if (rules.length > MAX_REASON_RULES) fail(`profile.reporting.reasons[${i}].rules`, `must list at most ${MAX_REASON_RULES} rule numbers`);
|
|
571
|
+
setOwn(reason, 'rules', rules.filter((n, at) => rules.findIndex((other) => Object.is(other, n)) === at));
|
|
572
|
+
});
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/** A profile written before `durations`, `customDuration` and `reporting` existed gets their defaults. */
|
|
576
|
+
function fillDefaults(copy: unknown): void {
|
|
577
|
+
if (!isPlain(copy)) return;
|
|
578
|
+
if (!Object.hasOwn(copy, 'durations')) setOwn(copy, 'durations', [...DEFAULT_DURATIONS]);
|
|
579
|
+
if (!Object.hasOwn(copy, 'customDuration')) setOwn(copy, 'customDuration', true);
|
|
580
|
+
// A section of the wrong shape is left as it is, for the validator to name; one that checks out is filled in.
|
|
581
|
+
setOwn(copy, 'reporting', fillReporting(copy['reporting']));
|
|
582
|
+
dedupeReasonRules(copy);
|
|
583
|
+
}
|
|
584
|
+
|
|
408
585
|
/** Copy, validate and freeze. Nothing returned shares structure with the input. */
|
|
409
|
-
function finalize(value: unknown):
|
|
586
|
+
function finalize(value: unknown): ResolvedProfile {
|
|
410
587
|
const copy = clone(value);
|
|
411
588
|
dedupeRuleLists(copy);
|
|
589
|
+
fillDefaults(copy);
|
|
412
590
|
validateProfile(copy);
|
|
413
|
-
return deepFreeze(copy);
|
|
591
|
+
return deepFreeze(copy as ResolvedProfile);
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
/**
|
|
595
|
+
* A copy of a profile with `durations` and `customDuration` filled in where it has none (a 0.1.1 profile). The input is not
|
|
596
|
+
* changed and the profile is not validated here (`validateProfile` does that). Used by the document functions.
|
|
597
|
+
*/
|
|
598
|
+
export function withDurationDefaults(p: ModerationProfile): ResolvedProfile {
|
|
599
|
+
return { ...p, durations: p.durations ?? [...DEFAULT_DURATIONS], customDuration: p.customDuration ?? true, reporting: resolveReporting(p.reporting) };
|
|
414
600
|
}
|
|
415
601
|
|
|
416
602
|
// ---------------------------------------------------------------------------------------------------------------
|
|
@@ -486,6 +672,8 @@ const RELAXED: ModerationProfile = {
|
|
|
486
672
|
rules: 'relaxed',
|
|
487
673
|
areaRules: [5, 6],
|
|
488
674
|
severeRules: [1],
|
|
675
|
+
durations: [...DEFAULT_DURATIONS],
|
|
676
|
+
customDuration: true,
|
|
489
677
|
levels: LEVELS,
|
|
490
678
|
guidelines: [
|
|
491
679
|
{
|
|
@@ -553,6 +741,8 @@ const STANDARD: ModerationProfile = {
|
|
|
553
741
|
rules: 'standard',
|
|
554
742
|
areaRules: [5, 6],
|
|
555
743
|
severeRules: [1],
|
|
744
|
+
durations: [...DEFAULT_DURATIONS],
|
|
745
|
+
customDuration: true,
|
|
556
746
|
levels: LEVELS,
|
|
557
747
|
guidelines: [
|
|
558
748
|
{
|
|
@@ -628,6 +818,8 @@ const STRICT: ModerationProfile = {
|
|
|
628
818
|
rules: 'strict',
|
|
629
819
|
areaRules: [5, 6],
|
|
630
820
|
severeRules: [1],
|
|
821
|
+
durations: [...DEFAULT_DURATIONS],
|
|
822
|
+
customDuration: true,
|
|
631
823
|
levels: STRICT_LEVELS,
|
|
632
824
|
guidelines: [
|
|
633
825
|
{
|
|
@@ -673,7 +865,7 @@ const STRICT: ModerationProfile = {
|
|
|
673
865
|
};
|
|
674
866
|
|
|
675
867
|
/** The three presets, complete, valid and deep-frozen. Values are the standards doc's tables. */
|
|
676
|
-
export const PRESETS: Readonly<Record<'relaxed' | 'standard' | 'strict',
|
|
868
|
+
export const PRESETS: Readonly<Record<'relaxed' | 'standard' | 'strict', ResolvedProfile>> = Object.freeze({
|
|
677
869
|
relaxed: finalize(RELAXED),
|
|
678
870
|
standard: finalize(STANDARD),
|
|
679
871
|
strict: finalize(STRICT),
|
|
@@ -697,7 +889,7 @@ export type PresetName = keyof typeof PRESETS;
|
|
|
697
889
|
export function resolveProfile(
|
|
698
890
|
preset: ModerationProfile | PresetName,
|
|
699
891
|
overrides: ProfileOverrides = {},
|
|
700
|
-
):
|
|
892
|
+
): ResolvedProfile {
|
|
701
893
|
let base: ModerationProfile;
|
|
702
894
|
if (typeof preset === 'string') {
|
|
703
895
|
if (!Object.hasOwn(PRESETS, preset)) return fail('preset', "must be 'relaxed', 'standard', 'strict' or a profile");
|
|
@@ -709,9 +901,172 @@ export function resolveProfile(
|
|
|
709
901
|
}
|
|
710
902
|
|
|
711
903
|
/**
|
|
712
|
-
* Validate a complete custom profile. Nothing is merged
|
|
713
|
-
* passed afterwards cannot change a profile that
|
|
904
|
+
* Validate a complete custom profile. Nothing is merged (a profile that leaves out `durations` or `customDuration` gets
|
|
905
|
+
* their defaults). Returns a deep-frozen copy, so editing the object you passed afterwards cannot change a profile that
|
|
906
|
+
* was already checked. Throws {@link ProfileError}.
|
|
714
907
|
*/
|
|
715
|
-
export function defineProfile(p: ModerationProfile):
|
|
908
|
+
export function defineProfile(p: ModerationProfile): ResolvedProfile {
|
|
716
909
|
return finalize(p);
|
|
717
910
|
}
|
|
911
|
+
|
|
912
|
+
// ---------------------------------------------------------------------------------------------------------------
|
|
913
|
+
// The policy layer: what a moderator may edit at runtime
|
|
914
|
+
|
|
915
|
+
/**
|
|
916
|
+
* The parts of a profile the hub may edit, and the order they are listed in. Everything else (identity, the written
|
|
917
|
+
* levels, the AI context, profanity handling) stays in code: changing profanity means rebuilding the filter.
|
|
918
|
+
*/
|
|
919
|
+
export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting'] as const;
|
|
920
|
+
export type PolicySection = (typeof POLICY_SECTIONS)[number];
|
|
921
|
+
|
|
922
|
+
/** One ladder cell as the editor sends it: the label may be left out and is then generated ("Restrict chat 6 hours"). */
|
|
923
|
+
export interface PolicyCell {
|
|
924
|
+
kind: 'chat' | 'area' | 'ban' | 'warning';
|
|
925
|
+
durationMs: number | null;
|
|
926
|
+
label?: string;
|
|
927
|
+
}
|
|
928
|
+
|
|
929
|
+
/** One ladder row as the editor sends it. */
|
|
930
|
+
export interface PolicyLadderRow {
|
|
931
|
+
step: LadderStep;
|
|
932
|
+
lowMedium: PolicyCell;
|
|
933
|
+
high: PolicyCell;
|
|
934
|
+
}
|
|
935
|
+
|
|
936
|
+
/**
|
|
937
|
+
* The stored edits: a deep-partial of the editable sections. An object section merges key by key onto the profile
|
|
938
|
+
* (`firstOffense`, `repeat`); a list replaces the profile's list whole (`durations`, `ladder` as all 6 rows, `areaRules`,
|
|
939
|
+
* `severeRules`). `guidelines` is positional: entry `i` holds the new `outcome` text of the profile's guideline tier `i`,
|
|
940
|
+
* and `null` leaves that tier as it is. A layer that touches anything else is refused.
|
|
941
|
+
*/
|
|
942
|
+
export interface PolicyLayer {
|
|
943
|
+
durations?: number[];
|
|
944
|
+
customDuration?: boolean;
|
|
945
|
+
ladder?: PolicyLadderRow[];
|
|
946
|
+
firstOffense?: Partial<Record<ConductLevel, Outcome>>;
|
|
947
|
+
repeat?: Partial<ModerationProfile['repeat']>;
|
|
948
|
+
areaRules?: number[];
|
|
949
|
+
severeRules?: number[];
|
|
950
|
+
guidelines?: Array<{ outcome: string } | null>;
|
|
951
|
+
/** The reporting settings: `flow` and `thanks` replace the profile's; `reasons` replaces the whole list. Each is optional; a reason needs only `id` and `label`. */
|
|
952
|
+
reporting?: ReportingSettings;
|
|
953
|
+
}
|
|
954
|
+
|
|
955
|
+
/** The longest outcome text a layer may set on a guideline tier. */
|
|
956
|
+
export const MAX_GUIDELINE_OUTCOME = 1000;
|
|
957
|
+
|
|
958
|
+
/** The label generated for a ladder cell with none, or null when the cell is not valid (the validator names why). */
|
|
959
|
+
function generatedLabel(kind: unknown, durationMs: unknown): string | null {
|
|
960
|
+
if (typeof kind !== 'string' || !CELL_KINDS.includes(kind)) return null;
|
|
961
|
+
if (kind === 'warning') return 'Warning';
|
|
962
|
+
if (durationMs !== null && !(positiveInt(durationMs) && durationMs <= MAX_DURATION_MS)) return null;
|
|
963
|
+
return outcomeLabel({ kind: kind as 'chat' | 'area' | 'ban', durationMs });
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
function withLabel(cell: unknown): unknown {
|
|
967
|
+
if (!isPlain(cell) || Object.hasOwn(cell, 'label')) return cell;
|
|
968
|
+
return { ...cell, label: generatedLabel(cell['kind'], cell['durationMs']) ?? '-' };
|
|
969
|
+
}
|
|
970
|
+
|
|
971
|
+
function ladderOverride(v: unknown): unknown {
|
|
972
|
+
if (!Array.isArray(v)) return fail('profile.ladder', `must have exactly ${LADDER_ROWS} rows, steps 0 to 5`);
|
|
973
|
+
return v.map((row: unknown) => (isPlain(row) ? { ...row, lowMedium: withLabel(row['lowMedium']), high: withLabel(row['high']) } : row));
|
|
974
|
+
}
|
|
975
|
+
|
|
976
|
+
function guidelinesOverride(base: ModerationProfile, v: unknown): unknown {
|
|
977
|
+
if (!Array.isArray(v)) return fail('profile.guidelines', 'must be a list of outcome texts, one per guideline tier');
|
|
978
|
+
if (v.length > base.guidelines.length) fail('profile.guidelines', 'has more entries than the profile has guideline tiers');
|
|
979
|
+
return base.guidelines.map((tier, i) => {
|
|
980
|
+
const entry: unknown = v[i];
|
|
981
|
+
if (entry === undefined || entry === null) return clone(tier);
|
|
982
|
+
const path = `profile.guidelines[${i}]`;
|
|
983
|
+
if (!isPlain(entry)) return fail(path, 'must be an object with an outcome, or null');
|
|
984
|
+
if (!Object.hasOwn(entry, 'outcome')) fail(`${path}.outcome`, 'is required');
|
|
985
|
+
for (const k of Object.keys(entry)) if (k !== 'outcome') fail(`${path}.${k}`, 'is not an editable setting');
|
|
986
|
+
const outcomeText = entry['outcome'];
|
|
987
|
+
if (typeof outcomeText !== 'string' || outcomeText.trim() === '') return fail(`${path}.outcome`, 'must be a non-empty string');
|
|
988
|
+
if (outcomeText.length > MAX_GUIDELINE_OUTCOME) fail(`${path}.outcome`, `must be at most ${MAX_GUIDELINE_OUTCOME} characters`);
|
|
989
|
+
return { ...(clone(tier) as Record<string, unknown>), outcome: outcomeText };
|
|
990
|
+
});
|
|
991
|
+
}
|
|
992
|
+
|
|
993
|
+
/** An outcome written as an object must say both `kind` and `durationMs`: a layer is self-contained, never half merged onto the base. */
|
|
994
|
+
function wholeOutcome(v: unknown, path: string): void {
|
|
995
|
+
if (!isPlain(v)) return;
|
|
996
|
+
if (!Object.hasOwn(v, 'kind')) fail(`${path}.kind`, 'is required');
|
|
997
|
+
if (!Object.hasOwn(v, 'durationMs')) fail(`${path}.durationMs`, 'is required');
|
|
998
|
+
}
|
|
999
|
+
|
|
1000
|
+
function layerToOverrides(base: ModerationProfile, layer: unknown): Record<string, unknown> {
|
|
1001
|
+
if (!isPlain(layer)) return fail('profile', 'must be an object');
|
|
1002
|
+
for (const key of Object.keys(layer)) {
|
|
1003
|
+
if (!(POLICY_SECTIONS as readonly string[]).includes(key)) fail(`profile.${key}`, 'is not an editable setting');
|
|
1004
|
+
}
|
|
1005
|
+
const out: Record<string, unknown> = {};
|
|
1006
|
+
for (const key of Object.keys(layer)) {
|
|
1007
|
+
const value = layer[key];
|
|
1008
|
+
if (value === undefined) continue;
|
|
1009
|
+
if (key === 'firstOffense' && isPlain(value)) {
|
|
1010
|
+
for (const level of Object.keys(value)) wholeOutcome(value[level], `profile.firstOffense.${level}`);
|
|
1011
|
+
}
|
|
1012
|
+
if (key === 'repeat' && isPlain(value)) wholeOutcome(value['outcome'], 'profile.repeat.outcome');
|
|
1013
|
+
if (key === 'ladder') setOwn(out, key, ladderOverride(value));
|
|
1014
|
+
else if (key === 'guidelines') setOwn(out, key, guidelinesOverride(base, value));
|
|
1015
|
+
else setOwn(out, key, value);
|
|
1016
|
+
}
|
|
1017
|
+
return out;
|
|
1018
|
+
}
|
|
1019
|
+
|
|
1020
|
+
/** The same error, with the path named from the layer the editor sent (`profile.ladder[2]` is `layer.ladder[2]`). */
|
|
1021
|
+
function inLayerTerms(err: ProfileError): ProfileError {
|
|
1022
|
+
const path = err.path === 'profile' ? 'layer' : err.path.startsWith('profile.') ? `layer.${err.path.slice('profile.'.length)}` : err.path;
|
|
1023
|
+
return new ProfileError(path, err.reason);
|
|
1024
|
+
}
|
|
1025
|
+
|
|
1026
|
+
/**
|
|
1027
|
+
* The effective profile: `base` (a preset with the code overrides) with the stored `layer` merged on top, validated. The
|
|
1028
|
+
* result is a deep-frozen copy that shares nothing with either. Throws {@link ProfileError} whose `path` starts with
|
|
1029
|
+
* `layer` (`layer.profanity`, `layer.ladder[2].high.durationMs`): a layer that touches a setting outside
|
|
1030
|
+
* {@link POLICY_SECTIONS}, or one that would make the profile invalid.
|
|
1031
|
+
*/
|
|
1032
|
+
export function applyPolicyLayer(base: ModerationProfile, layer: PolicyLayer): ResolvedProfile {
|
|
1033
|
+
try {
|
|
1034
|
+
return finalize(merge(base, layerToOverrides(base, layer)));
|
|
1035
|
+
} catch (err) {
|
|
1036
|
+
throw err instanceof ProfileError ? inLayerTerms(err) : err;
|
|
1037
|
+
}
|
|
1038
|
+
}
|
|
1039
|
+
|
|
1040
|
+
/** The editable sections a layer holds, in {@link POLICY_SECTIONS} order. */
|
|
1041
|
+
export function layerSections(layer: unknown): PolicySection[] {
|
|
1042
|
+
if (!isPlain(layer)) return [];
|
|
1043
|
+
return POLICY_SECTIONS.filter((s) => Object.hasOwn(layer, s));
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
function sameValue(a: unknown, b: unknown): boolean {
|
|
1047
|
+
if (Object.is(a, b)) return true;
|
|
1048
|
+
if (Array.isArray(a) || Array.isArray(b)) {
|
|
1049
|
+
return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x: unknown, i) => sameValue(x, b[i]));
|
|
1050
|
+
}
|
|
1051
|
+
if (isPlain(a) && isPlain(b)) {
|
|
1052
|
+
const ka = Object.keys(a);
|
|
1053
|
+
return ka.length === Object.keys(b).length && ka.every((k) => Object.hasOwn(b, k) && sameValue(a[k], b[k]));
|
|
1054
|
+
}
|
|
1055
|
+
return false;
|
|
1056
|
+
}
|
|
1057
|
+
|
|
1058
|
+
/** The sections that differ between two layers (present in one and not the other, or with other values), in order. */
|
|
1059
|
+
export function changedSections(before: unknown, after: unknown): PolicySection[] {
|
|
1060
|
+
const a = isPlain(before) ? before : {};
|
|
1061
|
+
const b = isPlain(after) ? after : {};
|
|
1062
|
+
return POLICY_SECTIONS.filter((s) => {
|
|
1063
|
+
const inA = Object.hasOwn(a, s);
|
|
1064
|
+
const inB = Object.hasOwn(b, s);
|
|
1065
|
+
return inA !== inB || (inA && !sameValue(a[s], b[s]));
|
|
1066
|
+
});
|
|
1067
|
+
}
|
|
1068
|
+
|
|
1069
|
+
/** A deep-frozen copy of a plain value (a stored layer, handed out read-only). */
|
|
1070
|
+
export function frozenCopy<T>(v: T): T {
|
|
1071
|
+
return deepFreeze(clone(v)) as T;
|
|
1072
|
+
}
|