founder-schema 0.2.0 → 0.4.0

package/dist/domains/moderation/moderation.js

@@ -0,0 +1,90 @@
+/**
+ * founder-schema: moderation
+ *
+ *   GET  /api/v1/moderation/queue                            ?limit&cursor
+ *        what members reported and nobody has decided on, oldest report first
+ *   GET  /api/v1/moderation/content                          ?state&limit&cursor
+ *        by state, newest first: visible is posts and polls by when posted;
+ *        hidden and removed also hold comments (so a hidden comment can be
+ *        found and put back), by when hidden or removed
+ *   A decision that changes nothing (hiding what is already hidden, removing
+ *   what its author deleted) leaves the reports open and writes nothing: for
+ *   those, dismiss.
+ *   POST /api/v1/moderation/:contentKind/:contentId/decision { action, note? }
+ *        decide on one post, poll or comment; answers the item as it now is
+ *
+ * ONE ITEM PER THING, NOT PER REPORT. Five members reporting one post is one
+ * row with five reports, so a moderator decides once. The queue's order is
+ * the oldest open report first: whoever has waited longest is seen first, and
+ * a pile-on cannot jump the line.
+ *
+ * THE DECISIONS
+ *   dismiss  it stays up; its open reports close as dismissed
+ *   hide     out of every feed and thread, kept, restorable; reports actioned
+ *   restore  a hidden item goes back up
+ *   remove   deleted as its author deleting it would (counts move), not
+ *            restorable from here; reports actioned
+ * Every decision on someone else's content is written to the audit log, with
+ * the note when there is one.
+ *
+ * A report's `note` was written by a member: untrusted text, shown as text.
+ *
+ * @module founder-schema/domains/moderation
+ */
+import { z } from 'zod';
+import { emptyStringToUndefined, objectIdSchema, optionalTrimmedString, paginationQuerySchema, } from '../../core/common.js';
+import { MODERATION_NOTE_MAX } from '../../core/limits.js';
+import { paginatedSchema } from '../../core/responses.js';
+import { contentKindSchema, engagementTargetKindSchema, reportReasonSchema } from '../feed/feed.js';
+/** Where a post, poll or comment stands. */
+export const MODERATION_STATE_VALUES = ['visible', 'hidden', 'removed'];
+export const moderationStateSchema = z.enum(MODERATION_STATE_VALUES);
+export const MODERATION_ACTION_VALUES = ['dismiss', 'hide', 'restore', 'remove'];
+export const moderationActionSchema = z.enum(MODERATION_ACTION_VALUES);
+const count = z.number().int().min(0);
+/** One post, poll or comment as moderation sees it. */
+export const moderationItemSchema = z.object({
+    target: z.object({ kind: engagementTargetKindSchema, id: objectIdSchema }),
+    /** The post or poll itself, or the one a comment is on: where it is read in the app. */
+    content: z.object({ kind: contentKindSchema, id: objectIdSchema }),
+    /** Its first words (a poll's question), cut to `MODERATION_EXCERPT_MAX`. */
+    excerpt: z.string(),
+    author: z.object({
+        id: objectIdSchema,
+        displayName: z.string(),
+        avatarUrl: z.url().nullable(),
+    }),
+    createdAt: z.iso.datetime(),
+    state: moderationStateSchema,
+    reports: z.object({
+        /** Reports nobody has decided on. */
+        open: count,
+        /** Every report ever filed about it. */
+        total: count,
+        /** Why it was reported, among the open ones, most-given first. */
+        reasons: z.array(z.object({ reason: reportReasonSchema, count })),
+        /** The reporters' notes, among the open ones, newest first (a few, not all). */
+        notes: z.array(z.string()),
+        /** When the oldest open report was filed. Null when none is open. */
+        oldestOpenAt: z.iso.datetime().nullable(),
+    }),
+    /** What the asking staff member may do to it now. */
+    viewer: z.object({
+        canDismiss: z.boolean(),
+        canHide: z.boolean(),
+        canRestore: z.boolean(),
+        canRemove: z.boolean(),
+    }),
+});
+export const moderationPageSchema = paginatedSchema(moderationItemSchema);
+/** `GET /moderation/content`. Visible when not said. */
+export const moderationContentQuerySchema = paginationQuerySchema.extend({
+    state: z.preprocess(emptyStringToUndefined, moderationStateSchema.default('visible')),
+});
+/** `POST /moderation/:contentKind/:contentId/decision`. */
+export const moderationDecisionBodySchema = z.object({
+    action: moderationActionSchema,
+    /** Why, for the audit log. Optional: an obvious spam removal needs no essay. */
+    note: optionalTrimmedString(MODERATION_NOTE_MAX),
+});
+//# sourceMappingURL=moderation.js.map

package/dist/domains/moderation/moderation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.js","sourceRoot":"","sources":["../../../src/domains/moderation/moderation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * founder-schema: moderation\n *\n *   GET  /api/v1/moderation/queue                            ?limit&cursor\n *        what members reported and nobody has decided on, oldest report first\n *   GET  /api/v1/moderation/content                          ?state&limit&cursor\n *        by state, newest first: visible is posts and polls by when posted;\n *        hidden and removed also hold comments (so a hidden comment can be\n *        found and put back), by when hidden or removed\n *   A decision that changes nothing (hiding what is already hidden, removing\n *   what its author deleted) leaves the reports open and writes nothing: for\n *   those, dismiss.\n *   POST /api/v1/moderation/:contentKind/:contentId/decision { action, note? }\n *        decide on one post, poll or comment; answers the item as it now is\n *\n * ONE ITEM PER THING, NOT PER REPORT. Five members reporting one post is one\n * row with five reports, so a moderator decides once. The queue's order is\n * the oldest open report first: whoever has waited longest is seen first, and\n * a pile-on cannot jump the line.\n *\n * THE DECISIONS\n *   dismiss  it stays up; its open reports close as dismissed\n *   hide     out of every feed and thread, kept, restorable; reports actioned\n *   restore  a hidden item goes back up\n *   remove   deleted as its author deleting it would (counts move), not\n *            restorable from here; reports actioned\n * Every decision on someone else's content is written to the audit log, with\n * the note when there is one.\n *\n * A report's `note` was written by a member: untrusted text, shown as text.\n *\n * @module founder-schema/domains/moderation\n */\n\nimport { z } from 'zod';\nimport {\n  emptyStringToUndefined,\n  objectIdSchema,\n  optionalTrimmedString,\n  paginationQuerySchema,\n} from '../../core/common.js';\nimport { MODERATION_NOTE_MAX } from '../../core/limits.js';\nimport { paginatedSchema } from '../../core/responses.js';\nimport { contentKindSchema, engagementTargetKindSchema, reportReasonSchema } from '../feed/feed.js';\n\n/** Where a post, poll or comment stands. */\nexport const MODERATION_STATE_VALUES = ['visible', 'hidden', 'removed'] as const;\nexport const moderationStateSchema = z.enum(MODERATION_STATE_VALUES);\nexport type ModerationState = z.infer<typeof moderationStateSchema>;\n\nexport const MODERATION_ACTION_VALUES = ['dismiss', 'hide', 'restore', 'remove'] as const;\nexport const moderationActionSchema = z.enum(MODERATION_ACTION_VALUES);\nexport type ModerationAction = z.infer<typeof moderationActionSchema>;\n\nconst count = z.number().int().min(0);\n\n/** One post, poll or comment as moderation sees it. */\nexport const moderationItemSchema = z.object({\n  target: z.object({ kind: engagementTargetKindSchema, id: objectIdSchema }),\n  /** The post or poll itself, or the one a comment is on: where it is read in the app. */\n  content: z.object({ kind: contentKindSchema, id: objectIdSchema }),\n  /** Its first words (a poll's question), cut to `MODERATION_EXCERPT_MAX`. */\n  excerpt: z.string(),\n  author: z.object({\n    id: objectIdSchema,\n    displayName: z.string(),\n    avatarUrl: z.url().nullable(),\n  }),\n  createdAt: z.iso.datetime(),\n  state: moderationStateSchema,\n  reports: z.object({\n    /** Reports nobody has decided on. */\n    open: count,\n    /** Every report ever filed about it. */\n    total: count,\n    /** Why it was reported, among the open ones, most-given first. */\n    reasons: z.array(z.object({ reason: reportReasonSchema, count })),\n    /** The reporters' notes, among the open ones, newest first (a few, not all). */\n    notes: z.array(z.string()),\n    /** When the oldest open report was filed. Null when none is open. */\n    oldestOpenAt: z.iso.datetime().nullable(),\n  }),\n  /** What the asking staff member may do to it now. */\n  viewer: z.object({\n    canDismiss: z.boolean(),\n    canHide: z.boolean(),\n    canRestore: z.boolean(),\n    canRemove: z.boolean(),\n  }),\n});\nexport type ModerationItem = z.infer<typeof moderationItemSchema>;\n\nexport const moderationPageSchema = paginatedSchema(moderationItemSchema);\nexport type ModerationPage = z.infer<typeof moderationPageSchema>;\n\n/** `GET /moderation/content`. Visible when not said. */\nexport const moderationContentQuerySchema = paginationQuerySchema.extend({\n  state: z.preprocess(emptyStringToUndefined, moderationStateSchema.default('visible')),\n});\nexport type ModerationContentQuery = z.infer<typeof moderationContentQuerySchema>;\nexport type ModerationContentQueryInput = z.input<typeof moderationContentQuerySchema>;\n\n/** `POST /moderation/:contentKind/:contentId/decision`. */\nexport const moderationDecisionBodySchema = z.object({\n  action: moderationActionSchema,\n  /** Why, for the audit log. Optional: an obvious spam removal needs no essay. */\n  note: optionalTrimmedString(MODERATION_NOTE_MAX),\n});\nexport type ModerationDecisionBody = z.infer<typeof moderationDecisionBodySchema>;\n"]}