@mintplayer/ng-spark 22.22.0 → 22.24.0

package/types/mintplayer-ng-spark-moderation.d.ts

@@ -0,0 +1,402 @@
+import { NavigationEnd, Routes } from "@angular/router";
+import * as i0 from "@angular/core";
+import { InjectionToken, OnInit, Provider } from "@angular/core";
+import { EntityAttributeDefinition, PersistentObject, QueryResultItem, SparkCellColumn } from "@mintplayer/ng-spark/models";
+import { SparkDetailContext } from "@mintplayer/ng-spark/panels";
+import { SparkAttributeRendererRegistration } from "@mintplayer/ng-spark/renderers";
+/** A target's score and the caller's vote (`/spark/moderation/vote`, `/votes`). */
+export interface ModerationVoteState {
+  id: string;
+  score: number;
+  up: number;
+  down: number;
+  /** +1, −1 or 0. */
+  myVote: -1 | 0 | 1;
+  locked: boolean;
+  /**
+   * Whether the caller holds the right to upvote / downvote this type (an earned privilege or a
+   * group grant). Not a promise the vote is accepted: an own post, a lock or a suspension still
+   * refuse it. Absent from an older server, which the widget reads as "may".
+   */
+  canUpvote?: boolean;
+  canDownvote?: boolean;
+}
+/** A user's reputation. Someone else's carries only `userId` and `total`. */
+export interface ModerationReputation {
+  userId: string;
+  total: number;
+  pending: number;
+  privileges: string[];
+  suspended: boolean;
+  /** The caller's own only: whether they may open the review queue (earned or granted). */
+  canReview?: boolean;
+}
+export interface ModerationReputationLine {
+  label: string;
+  kind: string;
+  points: number;
+  targetId?: string | null;
+  targetType?: string | null;
+  atUtc: string;
+  pending: boolean;
+}
+/** `/spark/moderation/status` — the moderator panel's view of one target. */
+export interface ModerationStatus {
+  id: string;
+  authorId?: string | null;
+  locked: boolean;
+  lockReason?: string | null;
+  canLock: boolean;
+  canReview: boolean;
+  canSuspend: boolean;
+  openCaseId?: string | null;
+  openFlags: number;
+}
+export interface ModerationCaseSummary {
+  id: string;
+  /** `flag`, or the fraud rule (`serial`, `concentration`, `reciprocal`, `fast-voting`, `registration-cluster`). */
+  kind: string;
+  status: string;
+  targetId?: string | null;
+  targetType?: string | null;
+  accountIds: string[];
+  flagCount: number;
+  voteCount: number;
+  summary?: string | null;
+  openedAtUtc: string;
+  decision?: string | null;
+}
+export interface ModerationCaseDetail {
+  case: ModerationCaseSummary;
+  matrix: {
+    voterId: string;
+    authorId: string;
+    votes: number;
+  }[];
+  timeline: {
+    voteId: string;
+    voterId: string;
+    authorId?: string | null;
+    targetId: string;
+    direction: number;
+    castAtUtc: string;
+    targetPostedAtUtc?: string | null;
+    secondsAfterPost?: number | null;
+  }[];
+  accounts: {
+    id: string;
+    createdAtUtc?: string | null;
+    ageDays?: number | null;
+    registrationMethod?: string | null;
+    /** How many other accounts share a network hash with this one — never an address. */
+    sharesNetworkWith: number;
+    reputationBefore: number;
+    reputationAfter: number;
+  }[];
+  flags: {
+    flaggerId: string;
+    reason: string;
+    raisedAtUtc: string;
+    status: string;
+  }[];
+}
+export interface ModerationAuditEntry {
+  id: string;
+  actorId?: string | null;
+  action: string;
+  targetId?: string | null;
+  targetType?: string | null;
+  subjectUserId?: string | null;
+  caseId?: string | null;
+  reason?: string | null;
+  details?: string | null;
+  atUtc: string;
+}
+/**
+ * Client for `MintPlayer.Spark.Moderation`'s endpoints (`/spark/moderation/*`, #460). Every call is
+ * a POST with the ids in the body — the route table is literal and RavenDB ids contain slashes.
+ *
+ * A target the caller cannot see (hidden, missing, not moderatable) is the standard refusal: 404
+ * (or 401 when signing in would help). A rule (own post, locked, suspended) is a 400 with `errors`,
+ * a quota (votes per day) a 429 whose `result.retryAfterSeconds` says when to try again.
+ */
+export declare class SparkModerationService {
+  #private;
+  private readonly spark;
+  private readonly pending;
+  private flushScheduled;
+  private readonly router;
+  /** Counts the caller's accepted votes, so the own reputation badge re-reads (a downvote costs reputation). */
+  readonly votesCast: import("@angular/core").Signal<number>;
+  private readonly navigated;
+  /**
+   * Changes whenever the caller's own reputation may have changed: after every navigation (a
+   * sign-in, a sign-out, another page) and after the caller's own votes. The own badge and the
+   * review-queue link read it to re-fetch {@link ownReputation}; a component in the app shell lives
+   * for the whole session and would otherwise show the first answer until a full reload.
+   */
+  readonly ownReputationChanged: import("@angular/core").Signal<{
+    navigation: NavigationEnd | null;
+    votes: number;
+  }>;
+  /**
+   * The caller's own reputation, shared by every caller in flight at once: the badge and the
+   * review-queue link both re-read on the same navigation and cost one request.
+   */
+  ownReputation(): Promise<ModerationReputation>;
+  /** Casts (+1 / −1) or withdraws (0) the caller's vote; resolves to the target's new state. */
+  vote(type: string, id: string, direction: -1 | 0 | 1): Promise<ModerationVoteState>;
+  /**
+   * The score and the caller's vote for one target, batched with every other call made in the same
+   * macrotask for the same type (one `POST /spark/moderation/votes`, ≤ 100 ids). Resolves to `null`
+   * for an id the server left out (not visible to the caller).
+   */
+  voteState(type: string, id: string): Promise<ModerationVoteState | null>;
+  /** `POST /spark/moderation/votes` for up to 100 ids of one type. */
+  votes(type: string, ids: string[]): Promise<ModerationVoteState[]>;
+  flag(type: string, id: string, reason: string): Promise<void>;
+  lock(type: string, id: string, reason?: string): Promise<void>;
+  unlock(type: string, id: string): Promise<void>;
+  /** What the moderator panel shows about a target, including which tools the caller holds. */
+  status(type: string, id: string): Promise<ModerationStatus>;
+  /** A user's reputation; the caller's own when `userId` is omitted (with privileges and suspension). */
+  reputation(userId?: string): Promise<ModerationReputation>;
+  /** The caller's own ledger, newest first. Voters are never named; a reversal reads "Voting corrected (−N)". */
+  history(take?: number): Promise<ModerationReputationLine[]>;
+  cases(status?: string, skip?: number, take?: number): Promise<ModerationCaseSummary[]>;
+  case(caseId: string): Promise<ModerationCaseDetail>;
+  /** `uphold` / `decline` (flag cases), `dismiss` / `reverse` / `merge` / `suspend` (fraud cases; the last two name `accountId`). */
+  decide(caseId: string, decision: string, accountId?: string, reason?: string): Promise<void>;
+  suspend(userId: string, days?: number | null, reason?: string): Promise<void>;
+  unsuspend(userId: string): Promise<void>;
+  audit(skip?: number, take?: number): Promise<ModerationAuditEntry[]>;
+  private flush;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkModerationService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** Where the review queue is routed; the moderator panel links there. Set by {@link provideSparkModeration}. */
+export declare const SPARK_MODERATION_REVIEW_PATH: InjectionToken<string>;
+/**
+ * The vote widget (#460): up, score, down. An attribute renderer — register it with
+ * {@link sparkModerationRenderers} and give an attribute of an `IModeratable` type
+ * `"renderer": "spark-vote"`. The attribute's own value is ignored: the score comes from
+ * `/spark/moderation/votes` (batched per page), never from the document, so a vote never moves the
+ * row's etag.
+ *
+ * An arrow the caller holds no right for (`canUpvote` / `canDownvote` false on the state) is
+ * disabled, so a user without the privilege sees the score but is not offered a click that the server
+ * refuses — except the active arrow, since withdrawing a vote needs no right.
+ *
+ * On the detail page the entity type is the object's. In a query grid a row carries no type, so the
+ * column needs `"rendererOptions": { "type": "<entity type id or alias>" }`.
+ */
+export declare class SparkVoteComponent {
+  private readonly moderation;
+  value: import("@angular/core").InputSignal<unknown>;
+  attribute: import("@angular/core").InputSignal<EntityAttributeDefinition | undefined>;
+  column: import("@angular/core").InputSignal<SparkCellColumn | undefined>;
+  options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  item: import("@angular/core").InputSignal<Record<string, any> | PersistentObject | QueryResultItem | undefined>;
+  protected readonly state: import("@angular/core").WritableSignal<ModerationVoteState | null>;
+  protected readonly busy: import("@angular/core").WritableSignal<boolean>;
+  protected readonly error: import("@angular/core").WritableSignal<string | null>;
+  protected readonly target: import("@angular/core").Signal<{
+    id: string;
+    type: string;
+  } | null>;
+  constructor();
+  cast(direction: 1 | -1): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkVoteComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkVoteComponent, "spark-vote", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "attribute": {
+      "alias": "attribute";
+      "required": false;
+      "isSignal": true;
+    };
+    "column": {
+      "alias": "column";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+    "item": {
+      "alias": "item";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** A readable message for a refused moderation call (400 errors, 429 quota, 404 refusal). */
+export declare function describeModerationError(e: unknown): string;
+/**
+ * **Flag** on the detail page of every object (#460). Registered by {@link provideSparkModeration}
+ * as a `SPARK_DETAIL_ACTIONS` entry. The button is offered to every signed-in viewer of a live row;
+ * the server decides (`Flag/T`, a visible moderatable row) and answers a refusal inline — the
+ * permissions endpoint does not report moderation rights, and a type that is not moderatable answers
+ * like a missing row, so the button cannot know in advance.
+ */
+export declare class SparkFlagButtonComponent {
+  private readonly moderation;
+  private readonly lang;
+  context: import("@angular/core").InputSignal<SparkDetailContext>;
+  protected readonly busy: import("@angular/core").WritableSignal<boolean>;
+  protected readonly done: import("@angular/core").WritableSignal<boolean>;
+  protected readonly error: import("@angular/core").WritableSignal<string | null>;
+  flag(): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkFlagButtonComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkFlagButtonComponent, "spark-flag-button", never, {
+    "context": {
+      "alias": "context";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The moderator panel under a moderatable object's detail page (#460): lock state and Lock/Unlock
+ * (`Lock/T`), open flags with a link to the review queue (`Review/Moderation`), and Suspend author
+ * (`Suspend/Moderation`). Restore/Purge and Revert are the SoftDelete and History entry points'.
+ * Renders nothing for a caller with none of these rights, or for a type that is not moderatable.
+ */
+export declare class SparkModeratorPanelComponent {
+  private readonly moderation;
+  private readonly lang;
+  protected readonly reviewPath: string;
+  context: import("@angular/core").InputSignal<SparkDetailContext>;
+  protected readonly status: import("@angular/core").WritableSignal<ModerationStatus | null>;
+  protected readonly busy: import("@angular/core").WritableSignal<boolean>;
+  protected readonly error: import("@angular/core").WritableSignal<string | null>;
+  constructor();
+  lock(): Promise<void>;
+  unlock(): Promise<void>;
+  suspendAuthor(userId: string): Promise<void>;
+  private run;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkModeratorPanelComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkModeratorPanelComponent, "spark-moderator-panel", never, {
+    "context": {
+      "alias": "context";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * A user's reputation (#460): `<spark-reputation-badge [userId]="post.authorId" />`, or without
+ * `userId` the signed-in user's own, with the not-yet-credited part (delayed crediting) beside it.
+ *
+ * The own badge usually sits in the app shell, which lives for the whole session: it re-reads the
+ * reputation after every navigation (a sign-in, a sign-out, opening another page) and after the
+ * caller's own votes, or it would show the first value it read until a full page reload.
+ */
+export declare class SparkReputationBadgeComponent {
+  private readonly moderation;
+  userId: import("@angular/core").InputSignal<string | null | undefined>;
+  protected readonly reputation: import("@angular/core").WritableSignal<ModerationReputation | null>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkReputationBadgeComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkReputationBadgeComponent, "spark-reputation-badge", never, {
+    "userId": {
+      "alias": "userId";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The review queue (#460): open cases on the left, the selected case's review surface on the right —
+ * the voter→target matrix, the timeline against the posts' creation, the accounts side by side (age,
+ * registration method, how many accounts share a network with it, reputation now and after reversing)
+ * and the rule that fired — with the decisions the case allows. Needs `Review/Moderation`; merge and
+ * suspend also `Suspend/Moderation` (the server refuses otherwise).
+ *
+ * Routed by {@link sparkModerationRoutes} at `moderation/review`; `?case=` selects a case.
+ */
+export declare class SparkReviewQueueComponent implements OnInit {
+  private readonly moderation;
+  private readonly route;
+  private readonly router;
+  private readonly spark;
+  protected readonly cases: import("@angular/core").WritableSignal<ModerationCaseSummary[]>;
+  /** Per case id: the target post's title and route, once resolved. */
+  protected readonly targets: import("@angular/core").WritableSignal<Record<string, {
+    title: string | null;
+    link: string[] | null;
+  }>>;
+  protected readonly selected: import("@angular/core").WritableSignal<ModerationCaseDetail | null>;
+  protected readonly busy: import("@angular/core").WritableSignal<boolean>;
+  protected readonly error: import("@angular/core").WritableSignal<string | null>;
+  ngOnInit(): Promise<void>;
+  open(caseId: string): Promise<void>;
+  decide(decision: string, accountId?: string): Promise<void>;
+  private load;
+  /**
+   * Names each case's post: its title (the object's breadcrumb) and a link to it. A case carries only
+   * the target's id and type name; without this the queue listed "flag · Spam" with no way to tell
+   * which post it was about. A target the caller cannot open (purged, hidden) keeps just its id.
+   */
+  private resolveTargets;
+  private run;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkReviewQueueComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkReviewQueueComponent, "spark-review-queue", never, {}, {}, never, never, true, never>;
+}
+/**
+ * A link to the review queue (#460) that renders only for a caller who may review — earned, or
+ * granted by a group such as moderators (`canReview` on the caller's own reputation). Anyone else
+ * would open a page whose every request answers 404. Re-checked after each navigation, so it appears
+ * on sign-in and disappears on sign-out.
+ *
+ * `<spark-review-queue-link linkClass="btn btn-sm btn-link" />` — `linkClass` styles the anchor.
+ */
+export declare class SparkReviewQueueLinkComponent {
+  private readonly moderation;
+  /** Classes for the anchor itself (the host element is only a wrapper). */
+  linkClass: import("@angular/core").InputSignal<string>;
+  protected readonly canReview: import("@angular/core").WritableSignal<boolean>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkReviewQueueLinkComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkReviewQueueLinkComponent, "spark-review-queue-link", never, {
+    "linkClass": {
+      "alias": "linkClass";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Adds the Moderation UI (#460) to the pages `sparkRoutes()` routes to: a **Flag** action on every
+ * detail page and the **moderator panel** under it. Needs the server package
+ * `MintPlayer.Spark.Moderation`.
+ *
+ * ```ts
+ * providers: [
+ *   provideSpark(...),
+ *   provideSparkModeration(),
+ *   provideSparkAttributeRenderers([...sparkModerationRenderers, ...yourRenderers]),
+ * ]
+ * // routes: [...sparkModerationRoutes(), ...sparkRoutes()]
+ * ```
+ *
+ * The vote widget is an attribute renderer (`"renderer": "spark-vote"` on an attribute of an
+ * `IModeratable` type), so it is registered through {@link sparkModerationRenderers} with the app's
+ * own renderers — `provideSparkAttributeRenderers` takes one list.
+ */
+export declare function provideSparkModeration(options?: {
+  reviewPath?: string;
+  panelOrder?: number;
+}): Provider[];
+/** The vote widget as an attribute renderer named `spark-vote` (detail page and grid column). */
+export declare const sparkModerationRenderers: SparkAttributeRendererRegistration[];
+/**
+ * The review-queue page at `moderation/review`. Put it **before** `sparkRoutes()` — a literal first
+ * segment is fine anywhere, but keeping add-on routes first avoids surprises with parameterised ones.
+ */
+export declare function sparkModerationRoutes(path?: string): Routes;

package/types/mintplayer-ng-spark-panels.d.ts

@@ -0,0 +1,108 @@
+import { InjectionToken, Provider, Type } from "@angular/core";
+import { EntityPermissions, EntityType, PersistentObject, SparkDeletedFilter, SparkQuery } from "@mintplayer/ng-spark/models";
+/**
+ * What a detail-page extension is told about the object on screen (#460).
+ *
+ * Handed to every {@link SPARK_DETAIL_PANELS} and {@link SPARK_DETAIL_ACTIONS} component through its
+ * `context` input. A new object is passed whenever the page's state changes (a reload, a patch), so a
+ * component reads it as a plain value and never needs to subscribe to anything.
+ */
+export interface SparkDetailContext {
+  /** The entity type id or alias from the route (`/po/:type/:id`). */
+  type: string;
+  /** The object id from the route. */
+  id: string;
+  item: PersistentObject;
+  entityType: EntityType;
+  /**
+   * Type-level rights (`/spark/permissions/{type}`). `null` while they load — treat as "not allowed".
+   * The optional add-on flags (`canRestore`, `canViewHistory`, …) are absent on an older server.
+   */
+  permissions: EntityPermissions | null;
+  /**
+   * The soft-deletion mode the object was loaded with — the route's `?deleted=` query parameter
+   * (`include` / `only`), or `null` for a normal load. `only` means the object was opened from the
+   * recycle bin and is a deleted row.
+   */
+  deleted: SparkDeletedFilter | null;
+  /** Re-fetches the object (and its permissions) with the same mode. */
+  reload(): Promise<void>;
+}
+/**
+ * What a query-page extension is told about the list on screen (#460).
+ *
+ * Handed to every {@link SPARK_QUERY_LIST_ACTIONS} component through its `context` input.
+ */
+export interface SparkQueryListContext {
+  query: SparkQuery;
+  /** Null for a query whose rows are not an entity type (a composed query). */
+  entityType: EntityType | null;
+  /** Type-level rights of `entityType`; null while they load or when there is no entity type. */
+  permissions: EntityPermissions | null;
+  /** The soft-deletion mode the list currently runs with (`exclude` unless the route says otherwise). */
+  deleted: SparkDeletedFilter;
+  /**
+   * Switches the list's soft-deletion mode. Written to the route as `?deleted=`, so the recycle bin
+   * survives a reload and the back button; `exclude` removes the parameter.
+   */
+  setDeleted(mode: SparkDeletedFilter): void;
+  /** Re-runs the query, keeping page and sort. */
+  reload(): void;
+}
+/**
+ * A component shown under the attributes of every routed detail page (`sparkRoutes()`'s
+ * `po/:type/:id`). It must declare `context = input.required<SparkDetailContext>()`.
+ *
+ * `sparkRoutes()` passes no templates to the pages it routes to, so a multi-provider is the only way
+ * an add-on (History, Moderation) can put something on them without the app replacing the page.
+ */
+export interface SparkDetailPanel {
+  /** Unique name; a second registration with the same id replaces the first. */
+  id: string;
+  component: Type<unknown>;
+  /** Ascending; panels without an order come last, in registration order. */
+  order?: number;
+}
+/**
+ * A component rendered in the action bar of every routed detail page, after the built-in and custom
+ * actions. It must declare `context = input.required<SparkDetailContext>()` and render nothing when
+ * it does not apply (it is responsible for its own permission checks).
+ */
+export interface SparkDetailAction {
+  id: string;
+  component: Type<unknown>;
+  /** Priority in the action bar's overflow ordering; defaults to 60. Lower stays visible longer. */
+  priority?: number;
+}
+/**
+ * A component rendered in the action bar of every routed query page (`query/:queryId`, `po/:type`).
+ * It must declare `context = input.required<SparkQueryListContext>()`.
+ */
+export interface SparkQueryListAction {
+  id: string;
+  component: Type<unknown>;
+  /** Priority in the action bar's overflow ordering; defaults to 60. */
+  priority?: number;
+}
+/** Multi-provider: panels under the attributes of the routed detail page. */
+export declare const SPARK_DETAIL_PANELS: InjectionToken<SparkDetailPanel[]>;
+/** Multi-provider: extra buttons in the routed detail page's action bar. */
+export declare const SPARK_DETAIL_ACTIONS: InjectionToken<SparkDetailAction[]>;
+/** Multi-provider: extra buttons in the routed query page's action bar. */
+export declare const SPARK_QUERY_LIST_ACTIONS: InjectionToken<SparkQueryListAction[]>;
+/** Registers detail panels (multi — every call adds). */
+export declare function provideSparkDetailPanels(...panels: SparkDetailPanel[]): Provider[];
+/** Registers detail-page actions (multi — every call adds). */
+export declare function provideSparkDetailActions(...actions: SparkDetailAction[]): Provider[];
+/** Registers query-page actions (multi — every call adds). */
+export declare function provideSparkQueryListActions(...actions: SparkQueryListAction[]): Provider[];
+/**
+ * Normalises a multi-provided list: the last registration of an id wins (so an app can replace a
+ * shipped panel by registering its own under the same id), then sorted by `key` ascending with
+ * unordered entries last, keeping registration order among equals.
+ */
+export declare function orderSparkExtensions<T extends {
+  id: string;
+}>(entries: readonly T[] | null | undefined, key: (entry: T) => number | undefined): T[];
+/** Reads `?deleted=` into a filter, ignoring anything that is not one of the three modes. */
+export declare function parseSparkDeletedParam(value: string | null | undefined): SparkDeletedFilter | null;