@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/types.ts CHANGED
@@ -2,6 +2,8 @@
2
2
  // their own sections below.
3
3
 
4
4
  import type { AuditListQuery, AuditRow } from './audit.js';
5
+ import type { PolicyLayer } from './profile.js';
6
+ import type { RuleRef } from './rules.js';
5
7
 
6
8
  // ---------------------------------------------------------------------------
7
9
  // Identity
@@ -173,6 +175,60 @@ export interface SanctionRow {
173
175
  * other load leaves the property off.
174
176
  */
175
177
  revokedAt?: number | null;
178
+ /**
179
+ * Who revoked the group and why. Set only by `listSubjectSanctions` (null while unrevoked, and on a row revoked
180
+ * before the actor was kept); every other load leaves the properties off.
181
+ */
182
+ revokedBy?: string | null;
183
+ revokeReason?: string | null;
184
+ }
185
+
186
+ /**
187
+ * What {@link Store.listSubjectSanctions} takes: the SUBJECT rows of sanction groups, newest first. Never an IP row.
188
+ */
189
+ export interface SanctionListQuery {
190
+ /** Only rows whose stored target is one of these subject ids (a person's canonical id and its aliases). Absent: everyone; empty: nobody. */
191
+ subjects?: readonly SubjectId[];
192
+ /** Only rows from this source. */
193
+ source?: Source;
194
+ /** Only rows with `startsAt >= since`. */
195
+ since?: number;
196
+ /**
197
+ * Only rows in force at this instant, of any age: not revoked, and with no end or an end strictly after it. Combines
198
+ * (AND) with the other filters.
199
+ */
200
+ activeAt?: number;
201
+ /**
202
+ * With `since`: also the rows older than `since` that are permanent (`endsAt` null) and not revoked. Ignored without
203
+ * `since`.
204
+ */
205
+ alsoPermanent?: boolean;
206
+ /** Keyset cursor: only rows older than this (`startsAt` below it, or equal with an id below `beforeId`). `beforeId` without `before` is ignored. */
207
+ before?: number;
208
+ beforeId?: string;
209
+ /** Clamped to 1..200 (a fraction is floored). */
210
+ limit: number;
211
+ }
212
+
213
+ /** What {@link Store.reporterTally} counts over the reports a person filed. `badFaith` is the number marked bad faith. */
214
+ export interface ReporterTally {
215
+ open: number;
216
+ actioned: number;
217
+ dismissed: number;
218
+ badFaith: number;
219
+ }
220
+
221
+ /**
222
+ * One decided report a person filed that carried a reason, with what its decision did: for the reporter's accuracy. `reason` is
223
+ * the report's stored `reportedReason`; `target` the reported subject as stored; `actions` one entry per sanction group the
224
+ * decision wrote (its subject row: who, and the rule cited, `'uncovered'` included). A dismissal with no actions has an empty list.
225
+ */
226
+ export interface ReporterDecision {
227
+ reportId: string;
228
+ status: 'actioned' | 'dismissed';
229
+ reason: string;
230
+ target: SubjectId;
231
+ actions: Array<{ subject: SubjectId; rule: RuleRef }>;
176
232
  }
177
233
 
178
234
  /**
@@ -247,7 +303,11 @@ export interface DiscordThreadRow {
247
303
  createdAt: number;
248
304
  }
249
305
 
250
- /** What a player may report another for. */
306
+ /**
307
+ * What a player could report another for in 0.1.1. A report's `category` is still one of these (derived from its reason, so
308
+ * code that reads `category` keeps working), but the reason a player picks is now `reportedReason`, an id from the profile's
309
+ * reporting reasons. `ReportInput.category` stays accepted as an alias of `reason`.
310
+ */
251
311
  export type ReportCategory = 'harassment' | 'hate' | 'cheating' | 'spam' | 'disruption' | 'other';
252
312
 
253
313
  /**
@@ -287,7 +347,14 @@ export interface StoredReport {
287
347
  targetSubject: SubjectId;
288
348
  targetSeat: string;
289
349
  targetHandle: string;
350
+ /** The 0.1.1 category this report is kept under, derived from `reportedReason` (`'other'` when none). Prefer `reportedReason`. */
290
351
  category: ReportCategory;
352
+ /**
353
+ * The reason the reporter gave: an id from the profile's reporting reasons, or null when they gave none. A HINT, never the
354
+ * truth: the case is settled by the moderator's decision. Optional on a row a store is given (missing reads as null); a
355
+ * store returns it on every record.
356
+ */
357
+ reportedReason?: string | null;
291
358
  note: string | null;
292
359
  lineId: string | null;
293
360
  excerpt: ReportExcerptLine[];
@@ -301,7 +368,18 @@ export interface StoredReport {
301
368
  * until then. `badFaith` marks a dismissal as the reporter's bad faith (it counts toward their suspension).
302
369
  * Private: moderator tools only.
303
370
  */
304
- export interface ReportRecord extends Omit<StoredReport, 'status'> {
371
+ export interface ReportRecord extends Omit<StoredReport, 'status' | 'reportedReason'> {
372
+ /**
373
+ * The reason the reporter gave (a reason id), or null. Rows stored before 0.1.2 carry their old category here (`disruption` as
374
+ * `griefing`). Every first-party store returns it; it is optional here so a custom store's 0.1.1-shaped record still type-checks (a
375
+ * missing one reads as the old category, see `StaffReport`, where it is always present).
376
+ */
377
+ reportedReason?: string | null;
378
+ /**
379
+ * When the reporter added their one follow-up (`cw.reports.addDetail`), epoch ms, or null. At most one per report, and only
380
+ * while the report is open.
381
+ */
382
+ detailAt?: number | null;
305
383
  status: 'open' | 'actioned' | 'dismissed';
306
384
  badFaith: boolean;
307
385
  actionedAt: number | null;
@@ -320,9 +398,64 @@ export interface ReportListQuery {
320
398
  /** Epoch ms; only reports created before this (exclusive), or at it with an id below `beforeId`. */
321
399
  before?: number;
322
400
  beforeId?: string;
401
+ /** Only reports whose `reportedReason` is this id; null keeps only those with none. Omit for all. */
402
+ reason?: string | null;
403
+ limit: number;
404
+ }
405
+
406
+ /** What {@link Store.listOpenReports} takes: the take-next scan, oldest first. */
407
+ export interface OpenReportQuery {
408
+ /** Only reports of this category. */
409
+ category?: ReportCategory;
410
+ /** Only reports whose `reportedReason` is this id; null keeps only those with none. Omit for all. A store must apply it. */
411
+ reason?: string | null;
412
+ /** Keyset cursor: only reports newer than this (`createdAt` above it, or equal with an id above `afterId`). `afterId` without `after` is ignored. */
413
+ after?: number;
414
+ afterId?: string;
415
+ /** Clamped to 1..200 (a fraction is floored). */
323
416
  limit: number;
324
417
  }
325
418
 
419
+ // ---------------------------------------------------------------------------
420
+ // Team workbench (storage shapes): soft claims and saved reasons
421
+ // ---------------------------------------------------------------------------
422
+
423
+ /** How long a claim lasts after the last claim or heartbeat: 10 minutes. */
424
+ export const CLAIM_TTL_MS = 10 * 60 * 1000;
425
+
426
+ /**
427
+ * A soft claim on a person's case: `by` (a staff actor) is handling it from `since` until `until` (epoch ms). It is live
428
+ * strictly before `until`; an expired claim reads as absent. Staff only: `person` is a subject id.
429
+ */
430
+ export interface ClaimRow {
431
+ person: SubjectId;
432
+ by: string;
433
+ since: number;
434
+ until: number;
435
+ }
436
+
437
+ /**
438
+ * How {@link Store.claimCase} treats a claim that someone else holds:
439
+ * - `claim`: wins when the case is free or the caller already holds it (a heartbeat).
440
+ * - `free`: wins only when nobody holds a live claim, the caller included (take next uses it to skip what it holds).
441
+ * - `takeover`: wins always (a senior moving a claim to themselves).
442
+ */
443
+ export type ClaimMode = 'claim' | 'free' | 'takeover';
444
+
445
+ /**
446
+ * What {@link Store.claimCase} answers. A win carries the claim now in force and `from`, the other actor whose LIVE claim
447
+ * this one replaced (null for a fresh claim, a heartbeat or an expired claim). A loss carries the live claim that stands.
448
+ */
449
+ export type ClaimAttempt = { won: true; claim: ClaimRow; from: string | null } | { won: false; claim: ClaimRow };
450
+
451
+ /** A saved decision reason: a short label for the picker and the text it fills in. */
452
+ export interface ReasonRow {
453
+ id: string;
454
+ label: string;
455
+ text: string;
456
+ active: boolean;
457
+ }
458
+
326
459
  /**
327
460
  * One recorded moderator decision, kept so the same decision sent twice is a replay and not a second action.
328
461
  * `key` is a hash of the report and the decision; `resultJson` is what the first call answered.
@@ -472,6 +605,13 @@ export interface Store {
472
605
  */
473
606
  loadSubjectActions(since: number): SanctionRow[];
474
607
 
608
+ /**
609
+ * The SUBJECT rows of sanction groups (never an IP row), newest first (`startsAt` descending, then `id` descending, so a
610
+ * tie is stable), revoked and ended ones included. Every row carries `revokedAt`, `revokedBy` and `revokeReason` (all
611
+ * null while unrevoked). See {@link SanctionListQuery}.
612
+ */
613
+ listSubjectSanctions(q: SanctionListQuery): SanctionRow[];
614
+
475
615
  /** Every subject row that carries a rule-gap note (any status, revoked or not), newest `startsAt` first. */
476
616
  listGaps(): SanctionRow[];
477
617
 
@@ -516,6 +656,15 @@ export interface Store {
516
656
  */
517
657
  loadAutoChatStarts(): Array<{ subject: SubjectId; startsAt: number }>;
518
658
 
659
+ /**
660
+ * Strikes at or after `since` (epoch ms), newest first (`at` descending, then `id` descending), at most `limit`
661
+ * (clamped to 1..500). The staff "blocked messages" view.
662
+ */
663
+ listStrikes(since: number, limit: number): StrikeRow[];
664
+
665
+ /** For each term id, how many strikes at or after `since` it earned (terms with none are absent). Order is unspecified. */
666
+ countStrikesByTerm(since: number): Array<{ termId: string; count: number }>;
667
+
519
668
  // Reports. SYNCHRONOUS on purpose (like sanctions): `ReportService.submit` runs these inside `transaction`.
520
669
  // Subject ids come back exactly as stored (canonical at write time, possibly merged since); the service folds
521
670
  // aliases. The table also carries `status`, `bad_faith` and `actioned_at` for K2's moderator tools.
@@ -532,7 +681,7 @@ export interface Store {
532
681
 
533
682
  /**
534
683
  * Reports newest first (`created_at` descending, then `id` descending, so a tie is stable), whole records. `status`
535
- * filters; `before` keeps only reports older than that instant (exclusive), and with `beforeId` also the ones filed
684
+ * filters; `reason` filters on `reportedReason` (an id, or null for none; a store must apply it, so paging stays right); `before` keeps only reports older than that instant (exclusive), and with `beforeId` also the ones filed
536
685
  * AT that instant whose id sorts below it (keyset paging: pass the last row's `createdAt` and `id`). `beforeId`
537
686
  * without `before` is ignored. `limit` is clamped to 1..200 (a fraction is floored).
538
687
  */
@@ -545,6 +694,46 @@ export interface Store {
545
694
  */
546
695
  listReportsByPerson(subjects: readonly SubjectId[], limit: number): ReportRecord[];
547
696
 
697
+ /**
698
+ * Reports that are still `open`, OLDEST first (`createdAt` ascending, then `id` ascending, so a tie is stable), whole
699
+ * records. `category` filters; `after` keeps only reports newer than that instant (exclusive), and with `afterId` also
700
+ * the ones filed AT that instant whose id sorts above it (keyset paging: pass the last row's `createdAt` and `id`).
701
+ * `limit` is clamped to 1..200 (a fraction is floored). The scan behind "take next".
702
+ */
703
+ listOpenReports(q: OpenReportQuery): ReportRecord[];
704
+
705
+ /**
706
+ * The OPEN reports filed AGAINST any of the given subjects (`targetSubject` as stored: pass the person's canonical id
707
+ * and every alias merged into it), newest first (`createdAt` descending, then `id` descending), whole records. `limit` is
708
+ * clamped to 1..200 (a fraction is floored). An empty list matches nothing.
709
+ */
710
+ listOpenReportsByPerson(subjects: readonly SubjectId[], limit: number): ReportRecord[];
711
+
712
+ /**
713
+ * How the reports FILED BY any of the given subjects stand (`reporterSubject` as stored: pass the person's canonical id
714
+ * and every alias merged into it): how many are still open, actioned or dismissed, and how many carry the bad-faith
715
+ * mark. An empty list counts nothing.
716
+ */
717
+ reporterTally(reporters: readonly SubjectId[]): ReporterTally;
718
+
719
+ /**
720
+ * OPTIONAL. The DECIDED reports (`actioned` or `dismissed`) filed by any of the given subjects (`reporterSubject` as stored)
721
+ * that carry a `reportedReason`, each with the sanction groups its decision wrote (the group's subject row: the person and
722
+ * the rule it cited). The reporter-accuracy read behind `reasonMatched` / `reasonDecided`. A store that leaves it out
723
+ * reports 0 and 0. An empty list matches nothing; open reports and reports with no reason are never returned. At most the newest
724
+ * 200 (newest first). A decision row that cannot be read is a decision with no actions, never an error.
725
+ */
726
+ loadReporterDecisions?(reporters: readonly SubjectId[]): ReporterDecision[];
727
+
728
+ /**
729
+ * OPTIONAL. Attach the reporter's one follow-up to an `open` report that has none yet: set `reportedReason` and `note` (the
730
+ * FINAL values; the caller has merged them with what the report had) and `detailAt`, atomically. Returns true when this call
731
+ * did it, false (nothing changed) for an unknown report, one that is no longer `open`, or one that already has a follow-up.
732
+ * Never touches the target, the excerpt or the line. A store that leaves it out cannot take a follow-up: `addDetail` answers
733
+ * `off`. `category` is the 0.1.1 category to keep beside the reason.
734
+ */
735
+ addReportDetail?(id: string, detail: { reportedReason: string | null; category: ReportCategory; note: string | null; at: number }): boolean;
736
+
548
737
  /**
549
738
  * Close a report that is still `open`: set its status, bad-faith mark, `actionedAt`, `actionedBy` and `modNote`,
550
739
  * and the bad-faith `evidence` (null or omitted when there is none). Returns true when this call closed it; false
@@ -581,10 +770,74 @@ export interface Store {
581
770
  */
582
771
  loadAutoChatGroups(since: number): Array<{ subject: SubjectId; groupId: string }>;
583
772
 
773
+ // Team workbench (K4 Task 4b). SYNCHRONOUS on purpose (like sanctions): they run inside `transaction`.
774
+
775
+ /**
776
+ * The change token: an opaque string that is different after every change a moderator's queue shows, and the same
777
+ * otherwise. It persists with the store (a restart does not rewind it) and is shared by every process on the same
778
+ * database. An adapter must move it INSIDE the same transaction as the write, so an undone write leaves it as it was,
779
+ * on exactly these events: `insertReport` (true), `closeReport` (true), `insertSanctionGroup` (true),
780
+ * `revokeSanctionGroup` (more than 0), `closeGap` (true), `claimCase` (a win that changes the owner of the case, so a
781
+ * heartbeat does not), `releaseClaim` (true), `insertReason`, and `updateReason` / `setReasonActive` when a value changes.
782
+ * Nothing else moves it, and reading it never does.
783
+ */
784
+ changeToken(): string;
785
+
786
+ /**
787
+ * Claim a person's case for `by` at `now`, the claim ending at `until`, as ONE atomic conditional write: of two callers
788
+ * racing for the same free case, exactly one wins, even from two processes on one database. See {@link ClaimMode} and
789
+ * {@link ClaimAttempt}. A claim is live strictly before its `until`; an expired one is replaced as if absent. `since` is
790
+ * kept across a heartbeat and set to `now` otherwise. The token moves when the owner of the case changes.
791
+ */
792
+ claimCase(person: SubjectId, by: string, now: number, until: number, mode: ClaimMode): ClaimAttempt;
793
+
794
+ /**
795
+ * Release `by`'s claim on the person. True only when it removed a LIVE claim held by `by`; someone else's claim, no claim
796
+ * and an expired claim (already absent) answer false and the first two are left alone.
797
+ */
798
+ releaseClaim(person: SubjectId, by: string, now: number): boolean;
799
+
800
+ /** The claims in force at `now` (not expired) among these people, ordered by person. An empty list matches nobody. */
801
+ loadClaims(persons: readonly SubjectId[], now: number): ClaimRow[];
802
+
803
+ /** Every saved reason (active or not), in the order they were added. */
804
+ listReasons(): ReasonRow[];
805
+
806
+ /** Add a reason. A duplicate `id` throws and writes nothing. */
807
+ insertReason(row: ReasonRow): void;
808
+
809
+ /** Change a reason's label and/or text. False for an unknown id; true otherwise (also when nothing differs). */
810
+ updateReason(id: string, patch: { label?: string; text?: string }): boolean;
811
+
812
+ /** Switch a reason on or off. False for an unknown id; true otherwise (also when it already was so). */
813
+ setReasonActive(id: string, active: boolean): boolean;
814
+
815
+ // The editable moderation profile (K4 Task 7f). OPTIONAL: a store without both methods still works, and `cw.policy.save`
816
+ // then answers `unsupported` while the profile stays code-only. SYNCHRONOUS on purpose (like sanctions).
817
+
818
+ /**
819
+ * The stored policy layer and its version, or null when none was ever saved (version 0). `layer` is whatever was saved,
820
+ * unvalidated: the kit checks it against the profile and ignores one it cannot use. A row that cannot be read at all (its text is
821
+ * not JSON) still answers its version, with a `layer` of null, which the kit reports as unusable. Returns a copy.
822
+ */
823
+ loadPolicyLayer?(): { layer: PolicyLayer; version: number } | null;
824
+
825
+ /**
826
+ * Replace the stored layer with `layer` IF the stored version is still `expectedVersion` (0 when none is stored), as ONE
827
+ * atomic conditional write: of two callers (two processes on one database included) that pass the same version, exactly
828
+ * one wins. Returns the new version (`expectedVersion + 1`), or null on a version conflict, which writes nothing. Runs
829
+ * inside `transaction`, so an undone transaction undoes it. It does not move the change token.
830
+ */
831
+ savePolicyLayer?(layer: PolicyLayer, expectedVersion: number): number | null;
832
+
584
833
  // Staff audit trail. SYNCHRONOUS on purpose (like sanctions). The trail also holds the rows `closeGap` and the term
585
834
  // editor write; none of these methods ever returns the json columns those carry (they may hold term text).
586
835
 
587
- /** Insert one audit entry. A duplicate id throws (nothing is written). Both json columns are written NULL. */
836
+ /**
837
+ * Insert one audit entry. A duplicate id throws (nothing is written). Both json columns are written NULL. A policy row
838
+ * (`policy.update`, `policy.reset`) also carries `detail` (the sections changed and the owner's reason): a store MUST keep it
839
+ * and return it from `listAudit`, or the trail silently loses what changed and why. A row without one has no `detail` key.
840
+ */
588
841
  insertAudit(row: AuditRow): void;
589
842
 
590
843
  /**