@atproto/ozone 0.1.172 → 0.1.174

package/src/report/activity.ts

@@ -0,0 +1,234 @@
+import { InvalidRequestError } from '@atproto/xrpc-server'
+import { Database } from '../db'
+import { Member } from '../lexicon/types/tools/ozone/team/defs'
+import {
+  AlreadyInTargetState,
+  InvalidStateTransition,
+  handleReportUpdate,
+} from './handle-report-update'
+
+export type ActivityType =
+  | 'queueActivity'
+  | 'assignmentActivity'
+  | 'escalationActivity'
+  | 'closeActivity'
+  | 'reopenActivity'
+  | 'noteActivity'
+
+export type CreateActivityParams = {
+  reportId: number
+  activityType: ActivityType
+  internalNote?: string
+  publicNote?: string
+  meta?: Record<string, unknown>
+  /** Set true for activities created by automated processes (e.g. queue router). */
+  isAutomated?: boolean
+  createdBy: string
+}
+
+export async function createReportActivity(
+  db: Database,
+  params: CreateActivityParams,
+) {
+  const {
+    reportId,
+    activityType,
+    internalNote,
+    publicNote,
+    meta,
+    isAutomated = false,
+    createdBy,
+  } = params
+
+  return db.transaction(async (dbTxn) => {
+    // Lock the report row for the duration of the transaction to prevent
+    // concurrent writes from racing on status validation + update.
+    const report = await dbTxn.db
+      .selectFrom('report')
+      .select(['id', 'status'])
+      .where('id', '=', reportId)
+      .forUpdate()
+      .executeTakeFirst()
+
+    if (!report) {
+      throw new InvalidRequestError(
+        `Report ${reportId} not found`,
+        'ReportNotFound',
+      )
+    }
+
+    let result
+    try {
+      result = handleReportUpdate(report.status, {
+        type: 'activity',
+        activityType,
+      })
+    } catch (err) {
+      if (err instanceof AlreadyInTargetState) {
+        throw new InvalidRequestError(err.message, 'AlreadyInTargetState')
+      }
+      if (err instanceof InvalidStateTransition) {
+        throw new InvalidRequestError(err.message, 'InvalidStateTransition')
+      }
+      throw err
+    }
+
+    const now = new Date().toISOString()
+
+    if (result.nextStatus !== null) {
+      const updateSet: Record<string, string | null> = {
+        status: result.nextStatus,
+        updatedAt: now,
+      }
+      if (result.nextStatus === 'closed') {
+        updateSet.closedAt = now
+      } else if (result.nextStatus === 'open') {
+        updateSet.closedAt = null
+      }
+      await dbTxn.db
+        .updateTable('report')
+        .set(updateSet)
+        .where('id', '=', reportId)
+        .execute()
+    }
+
+    const [activity] = await dbTxn.db
+      .insertInto('report_activity')
+      .values({
+        reportId,
+        activityType,
+        previousStatus: result.activity?.previousStatus ?? null,
+        internalNote: internalNote ?? null,
+        publicNote: publicNote ?? null,
+        meta: meta ?? null,
+        isAutomated,
+        createdBy,
+        createdAt: now,
+      })
+      .returningAll()
+      .execute()
+
+    return activity
+  })
+}
+
+export type BulkActivityInsert = {
+  reportId: number
+  activityType: string
+  previousStatus: string | null
+  internalNote?: string
+  publicNote?: string
+  meta?: unknown
+  isAutomated: boolean
+  createdBy: string
+  createdAt: string
+}
+
+/**
+ * Insert multiple activity rows in a single query. No validation — caller is
+ * responsible for correctness and for being inside an appropriate transaction.
+ */
+export async function bulkInsertReportActivities(
+  db: Database,
+  activities: BulkActivityInsert[],
+) {
+  if (!activities.length) return
+  await db.db
+    .insertInto('report_activity')
+    .values(
+      activities.map((a) => ({
+        reportId: a.reportId,
+        activityType: a.activityType,
+        previousStatus: a.previousStatus,
+        internalNote: a.internalNote ?? null,
+        publicNote: a.publicNote ?? null,
+        meta: a.meta ?? null,
+        isAutomated: a.isAutomated,
+        createdBy: a.createdBy,
+        createdAt: a.createdAt,
+      })),
+    )
+    .execute()
+}
+
+export type ListActivitiesParams = {
+  reportId: number
+  limit?: number
+  cursor?: string
+}
+
+export async function listReportActivities(
+  db: Database,
+  params: ListActivitiesParams,
+) {
+  const { reportId, limit = 50, cursor } = params
+
+  let builder = db.db
+    .selectFrom('report_activity')
+    .selectAll()
+    .where('reportId', '=', reportId)
+    .orderBy('createdAt', 'desc')
+    .orderBy('id', 'desc')
+    .limit(limit + 1)
+
+  if (cursor) {
+    const cursorId = parseInt(cursor, 10)
+    if (!isNaN(cursorId)) {
+      builder = builder.where('id', '<', cursorId)
+    }
+  }
+
+  const rows = await builder.execute()
+  const hasMore = rows.length > limit
+  const activities = hasMore ? rows.slice(0, limit) : rows
+
+  const nextCursor =
+    hasMore && activities.length > 0
+      ? String(activities[activities.length - 1].id)
+      : undefined
+
+  return { activities, cursor: nextCursor }
+}
+
+function buildActivityObject(
+  activityType: string,
+  previousStatus: string | null,
+): { $type: string; [k: string]: unknown } {
+  const $type = `tools.ozone.report.defs#${activityType}`
+  if (previousStatus !== null) {
+    return { $type, previousStatus }
+  }
+  return { $type }
+}
+
+export function formatActivityView(
+  activity: {
+    id: number
+    reportId: number
+    activityType: string
+    previousStatus: string | null
+    internalNote: string | null
+    publicNote: string | null
+    meta: unknown
+    isAutomated: boolean
+    createdBy: string
+    createdAt: string
+  },
+  memberViews?: Map<string, Member>,
+) {
+  return {
+    id: activity.id,
+    reportId: activity.reportId,
+    activity: buildActivityObject(
+      activity.activityType,
+      activity.previousStatus,
+    ),
+    internalNote: activity.internalNote ?? undefined,
+    publicNote: activity.publicNote ?? undefined,
+    meta: (activity.meta as Record<string, unknown>) ?? undefined,
+    isAutomated: activity.isAutomated,
+    createdBy: activity.createdBy,
+    moderator: memberViews?.get(activity.createdBy),
+    createdAt: activity.createdAt,
+  }
+}

package/src/report/handle-report-update.ts

@@ -0,0 +1,209 @@
+/**
+ * Pure, synchronous state-transition logic for reports.
+ *
+ * Every code path that changes a report's status or creates a report activity
+ * should call `handleReportUpdate` to determine the next status and the
+ * activity record to insert. This keeps the state machine in one place and
+ * decouples it from DB operations so it works for both single-row transactions
+ * and bulk updates.
+ */
+
+// ---------------------------------------------------------------------------
+// Error types — callers decide how to surface these (throw, skip, etc.)
+// ---------------------------------------------------------------------------
+
+export class AlreadyInTargetState extends Error {
+  constructor(
+    public currentStatus: string,
+    public targetStatus: string,
+  ) {
+    super(`Report is already in '${targetStatus}' status`)
+    this.name = 'AlreadyInTargetState'
+  }
+}
+
+export class InvalidStateTransition extends Error {
+  constructor(
+    public fromStatus: string,
+    public toStatus: string,
+  ) {
+    super(`Cannot transition report from '${fromStatus}' to '${toStatus}'`)
+    this.name = 'InvalidStateTransition'
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State machine tables
+// ---------------------------------------------------------------------------
+
+/** Valid state transitions: key = fromState, value = allowed toStates */
+export const VALID_TRANSITIONS: Record<string, string[]> = {
+  open: ['closed', 'escalated', 'queued', 'assigned'],
+  closed: ['open'],
+  escalated: ['open', 'closed'],
+  queued: ['assigned', 'open'],
+  assigned: ['open', 'closed', 'escalated', 'queued'],
+}
+
+/** Activity types that map to a specific target status */
+const ACTIVITY_TO_STATE: Record<string, string> = {
+  queueActivity: 'queued',
+  assignmentActivity: 'assigned',
+  escalationActivity: 'escalated',
+  closeActivity: 'closed',
+  reopenActivity: 'open',
+}
+
+/** Activity types that are only valid from specific source states */
+const ACTIVITY_VALID_FROM_STATES: Record<string, string[]> = {
+  reopenActivity: ['closed'],
+}
+
+/** Moderation event types → target status (+ activity type) */
+const EVENT_TYPE_MAP: Record<string, { status: string; activityType: string }> =
+  {
+    'tools.ozone.moderation.defs#modEventAcknowledge': {
+      status: 'closed',
+      activityType: 'closeActivity',
+    },
+    'tools.ozone.moderation.defs#modEventTakedown': {
+      status: 'closed',
+      activityType: 'closeActivity',
+    },
+    'tools.ozone.moderation.defs#modEventLabel': {
+      status: 'closed',
+      activityType: 'closeActivity',
+    },
+    'tools.ozone.moderation.defs#modEventComment': {
+      status: 'closed',
+      activityType: 'closeActivity',
+    },
+    'tools.ozone.moderation.defs#modEventEscalate': {
+      status: 'escalated',
+      activityType: 'escalationActivity',
+    },
+  }
+
+// ---------------------------------------------------------------------------
+// Action types — the three ways a report's status can change
+// ---------------------------------------------------------------------------
+
+export type ReportUpdateAction =
+  | { type: 'activity'; activityType: string }
+  | { type: 'event'; eventType: string }
+  | { type: 'queue' }
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export type ActivityRecord = {
+  activityType: string
+  previousStatus: string
+}
+
+export type ReportUpdateResult = {
+  nextStatus: string | null
+  activity: ActivityRecord | null
+}
+
+// ---------------------------------------------------------------------------
+// Core function
+// ---------------------------------------------------------------------------
+
+/**
+ * Determines the next status and activity record for a report update.
+ *
+ * @throws AlreadyInTargetState if the report is already in the target status
+ * @throws InvalidStateTransition if the transition is not allowed
+ * @returns nextStatus (null = no change) and activity (null = nothing to record)
+ */
+export function handleReportUpdate(
+  currentStatus: string,
+  action: ReportUpdateAction,
+): ReportUpdateResult {
+  switch (action.type) {
+    case 'activity':
+      return handleActivityAction(currentStatus, action.activityType)
+    case 'event':
+      return handleEventAction(currentStatus, action.eventType)
+    case 'queue':
+      return handleQueueAction(currentStatus)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Action handlers
+// ---------------------------------------------------------------------------
+
+function handleActivityAction(
+  currentStatus: string,
+  activityType: string,
+): ReportUpdateResult {
+  const toState = ACTIVITY_TO_STATE[activityType] ?? null
+
+  // Note-type activities — no state change, but still produce an activity record
+  if (toState === null) {
+    return { nextStatus: null, activity: null }
+  }
+
+  // Check activity-specific source-state constraints
+  const validFromStates = ACTIVITY_VALID_FROM_STATES[activityType]
+  if (validFromStates && !validFromStates.includes(currentStatus)) {
+    throw new InvalidStateTransition(currentStatus, toState)
+  }
+
+  validateTransition(currentStatus, toState)
+
+  return {
+    nextStatus: toState,
+    activity: { activityType, previousStatus: currentStatus },
+  }
+}
+
+function handleEventAction(
+  currentStatus: string,
+  eventType: string,
+): ReportUpdateResult {
+  const mapping = EVENT_TYPE_MAP[eventType]
+  if (!mapping) {
+    // Event type doesn't affect report status
+    return { nextStatus: null, activity: null }
+  }
+
+  validateTransition(currentStatus, mapping.status)
+
+  return {
+    nextStatus: mapping.status,
+    activity: {
+      activityType: mapping.activityType,
+      previousStatus: currentStatus,
+    },
+  }
+}
+
+function handleQueueAction(currentStatus: string): ReportUpdateResult {
+  // Queue routing only transitions open → queued
+  if (currentStatus !== 'open') {
+    return { nextStatus: null, activity: null }
+  }
+
+  return {
+    nextStatus: 'queued',
+    activity: { activityType: 'queueActivity', previousStatus: currentStatus },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared validation
+// ---------------------------------------------------------------------------
+
+function validateTransition(fromStatus: string, toStatus: string): void {
+  if (fromStatus === toStatus) {
+    throw new AlreadyInTargetState(fromStatus, toStatus)
+  }
+  const allowed = VALID_TRANSITIONS[fromStatus] ?? []
+  if (!allowed.includes(toStatus)) {
+    throw new InvalidStateTransition(fromStatus, toStatus)
+  }
+}

package/src/report/reassign.ts

@@ -0,0 +1,109 @@
+import { InvalidRequestError } from '@atproto/xrpc-server'
+import { Database } from '../db'
+import { QueueService } from '../queue/service'
+
+export type ReassignReportQueueParams = {
+  reportId: number
+  toQueueId: number
+  comment?: string
+  createdBy: string
+}
+
+export async function reassignReportQueue(
+  db: Database,
+  queueService: QueueService,
+  params: ReassignReportQueueParams,
+): Promise<void> {
+  const { reportId, toQueueId, comment, createdBy } = params
+
+  if (toQueueId !== -1) {
+    const queue = await queueService.getById(toQueueId)
+    if (!queue) {
+      throw new InvalidRequestError(
+        `Queue ${toQueueId} not found`,
+        'QueueNotFound',
+      )
+    }
+    if (!queue.enabled) {
+      throw new InvalidRequestError(
+        `Queue ${toQueueId} is disabled`,
+        'QueueDisabled',
+      )
+    }
+  }
+
+  await db.transaction(async (dbTxn) => {
+    const report = await dbTxn.db
+      .selectFrom('report')
+      .select(['id', 'status', 'queueId'])
+      .where('id', '=', reportId)
+      .forUpdate()
+      .executeTakeFirst()
+
+    if (!report) {
+      throw new InvalidRequestError(
+        `Report ${reportId} not found`,
+        'ReportNotFound',
+      )
+    }
+
+    if (report.status === 'closed') {
+      throw new InvalidRequestError(
+        `Report ${reportId} is closed and cannot be reassigned`,
+        'ReportClosed',
+      )
+    }
+
+    // NULL and -1 both mean "unassigned" for equivalence purposes.
+    const currentQueueId = report.queueId ?? -1
+    if (currentQueueId === toQueueId) {
+      throw new InvalidRequestError(
+        `Report ${reportId} is already in queue ${toQueueId}`,
+        'AlreadyInTargetQueue',
+      )
+    }
+
+    const previousStatus = report.status
+    let nextStatus: string = previousStatus
+    if (toQueueId !== -1 && previousStatus === 'open') {
+      nextStatus = 'queued'
+    } else if (toQueueId === -1 && previousStatus === 'queued') {
+      nextStatus = 'open'
+    }
+
+    const now = new Date().toISOString()
+
+    const reportUpdate: Record<string, string | number | null> = {
+      queueId: toQueueId,
+      queuedAt: toQueueId === -1 ? null : now,
+      updatedAt: now,
+    }
+    if (nextStatus !== previousStatus) {
+      reportUpdate.status = nextStatus
+    }
+
+    await dbTxn.db
+      .updateTable('report')
+      .set(reportUpdate)
+      .where('id', '=', reportId)
+      .execute()
+
+    await dbTxn.db
+      .insertInto('report_activity')
+      .values({
+        reportId,
+        activityType: 'queueActivity',
+        previousStatus,
+        internalNote: comment ?? null,
+        publicNote: null,
+        meta: {
+          fromQueueId: report.queueId ?? null,
+          toQueueId,
+        },
+        isAutomated: false,
+        createdBy,
+        createdAt: now,
+      })
+      .execute()
+  })
+}