@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.
Files changed (71) hide show
  1. package/README.md +128 -4
  2. package/dist/src/audit.d.ts +27 -5
  3. package/dist/src/audit.d.ts.map +1 -1
  4. package/dist/src/audit.js +57 -6
  5. package/dist/src/audit.js.map +1 -1
  6. package/dist/src/chatwarden.d.ts +183 -11
  7. package/dist/src/chatwarden.d.ts.map +1 -1
  8. package/dist/src/chatwarden.js +65 -10
  9. package/dist/src/chatwarden.js.map +1 -1
  10. package/dist/src/documents.d.ts +12 -2
  11. package/dist/src/documents.d.ts.map +1 -1
  12. package/dist/src/documents.js +56 -34
  13. package/dist/src/documents.js.map +1 -1
  14. package/dist/src/events.d.ts +3 -0
  15. package/dist/src/events.d.ts.map +1 -1
  16. package/dist/src/events.js.map +1 -1
  17. package/dist/src/index.d.ts +20 -11
  18. package/dist/src/index.d.ts.map +1 -1
  19. package/dist/src/index.js +11 -6
  20. package/dist/src/index.js.map +1 -1
  21. package/dist/src/ladder.d.ts +2 -0
  22. package/dist/src/ladder.d.ts.map +1 -1
  23. package/dist/src/ladder.js +1 -1
  24. package/dist/src/ladder.js.map +1 -1
  25. package/dist/src/policy.d.ts +129 -0
  26. package/dist/src/policy.d.ts.map +1 -0
  27. package/dist/src/policy.js +242 -0
  28. package/dist/src/policy.js.map +1 -0
  29. package/dist/src/profile.d.ts +120 -7
  30. package/dist/src/profile.d.ts.map +1 -1
  31. package/dist/src/profile.js +295 -7
  32. package/dist/src/profile.js.map +1 -1
  33. package/dist/src/reporting.d.ts +127 -0
  34. package/dist/src/reporting.d.ts.map +1 -0
  35. package/dist/src/reporting.js +172 -0
  36. package/dist/src/reporting.js.map +1 -0
  37. package/dist/src/reports.d.ts +80 -4
  38. package/dist/src/reports.d.ts.map +1 -1
  39. package/dist/src/reports.js +120 -6
  40. package/dist/src/reports.js.map +1 -1
  41. package/dist/src/staffReports.d.ts +17 -5
  42. package/dist/src/staffReports.d.ts.map +1 -1
  43. package/dist/src/staffReports.js +22 -5
  44. package/dist/src/staffReports.js.map +1 -1
  45. package/dist/src/staffViews.d.ts +138 -0
  46. package/dist/src/staffViews.d.ts.map +1 -0
  47. package/dist/src/staffViews.js +205 -0
  48. package/dist/src/staffViews.js.map +1 -0
  49. package/dist/src/team.d.ts +149 -0
  50. package/dist/src/team.d.ts.map +1 -0
  51. package/dist/src/team.js +385 -0
  52. package/dist/src/team.js.map +1 -0
  53. package/dist/src/types.d.ts +245 -4
  54. package/dist/src/types.d.ts.map +1 -1
  55. package/dist/src/types.js +5 -0
  56. package/dist/src/types.js.map +1 -1
  57. package/package.json +2 -2
  58. package/src/audit.ts +71 -7
  59. package/src/chatwarden.ts +245 -20
  60. package/src/documents.ts +70 -43
  61. package/src/events.ts +10 -1
  62. package/src/index.ts +109 -4
  63. package/src/ladder.ts +1 -1
  64. package/src/policy.ts +288 -0
  65. package/src/profile.ts +369 -14
  66. package/src/reporting.ts +251 -0
  67. package/src/reports.ts +163 -10
  68. package/src/staffReports.ts +33 -7
  69. package/src/staffViews.ts +325 -0
  70. package/src/team.ts +422 -0
  71. 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
- export interface ModerationProfile {
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 OPTIONAL_TOP_KEYS: readonly string[] = ['areaRules', 'severeRules'];
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).forEach((item, i) => {
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 OPTIONAL_TOP_KEYS) if (Object.hasOwn(p, key)) ruleList(p[key], `profile.${key}`);
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 OPTIONAL_TOP_KEYS) {
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): ModerationProfile {
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', ModerationProfile>> = Object.freeze({
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
- ): ModerationProfile {
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. Returns a deep-frozen copy, so editing the object you
713
- * passed afterwards cannot change a profile that was already checked. Throws {@link ProfileError}.
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): 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
+ }