feat: add punishment seen lookup

openapi/components/schemas/api-key-scope.yaml

@@ -18,5 +18,6 @@ enum:
   - players:read-details
   - players:write
   - punishments:read
+  - punishments:seen
   - punishments:write
   - stream:read

openapi/components/schemas/seen-player-summary.yaml

@@ -0,0 +1,25 @@
+type: object
+title: SeenPlayerSummary
+description: The current activity summary for a player in SpicyAzisaBan's database.
+required:
+  - id
+  - username
+  - ip
+  - lastSeenAt
+properties:
+  id:
+    type: string
+    format: uuid
+    description: The player's UUID.
+  username:
+    type: string
+    description: The player's most recently recorded name.
+  ip:
+    type:
+      - string
+      - "null"
+    description: The player's most recently recorded IP address, or `null` if it is unknown.
+  lastSeenAt:
+    type: string
+    format: date-time
+    description: The time at which the player was last seen.

openapi/components/schemas/seen-player.yaml

@@ -0,0 +1,71 @@
+type: object
+title: SeenPlayer
+description: The activity information recorded for a player in SpicyAzisaBan's database.
+required:
+  - id
+  - username
+  - ip
+  - lastSeenAt
+  - firstLoginAt
+  - firstLoginAttemptAt
+  - lastLoginAt
+  - lastLoginAttemptAt
+  - usernameHistory
+  - ipHistory
+  - sameIpPlayers
+properties:
+  id:
+    type: string
+    format: uuid
+    description: The player's UUID.
+  username:
+    type: string
+    description: The player's most recently recorded name.
+  ip:
+    type:
+      - string
+      - "null"
+    description: The player's most recently recorded IP address, or `null` if it is unknown.
+  lastSeenAt:
+    type: string
+    format: date-time
+    description: The time at which the player was last seen.
+  firstLoginAt:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The time at which the player first logged in, or `null` if unavailable.
+  firstLoginAttemptAt:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The first recorded login attempt, or `null` if unavailable.
+  lastLoginAt:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The last successful login, or `null` if unavailable.
+  lastLoginAttemptAt:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The last recorded login attempt, or `null` if unavailable.
+  usernameHistory:
+    type: array
+    description: Recorded player names in most-recent-first order, without duplicates.
+    items:
+      type: string
+  ipHistory:
+    type: array
+    description: Recorded IP addresses in most-recent-first order, without duplicates.
+    items:
+      type: string
+  sameIpPlayers:
+    type: array
+    description: Other players that have used the player's current IP address.
+    items:
+      $ref: "../../openapi.yaml#/components/schemas/SeenPlayerSummary"

openapi/components/schemas/seen-result.yaml

@@ -0,0 +1,26 @@
+title: SeenResult
+description: The result of a SpicyAzisaBan activity lookup.
+type: object
+required:
+  - kind
+  - players
+properties:
+  kind:
+    type: string
+    enum:
+      - player
+      - ip
+    description: Whether the target was resolved as a player or IP address.
+  player:
+    $ref: "../../openapi.yaml#/components/schemas/SeenPlayer"
+    description: Present when `kind` is `player`.
+  ip:
+    type: string
+    description: Present when `kind` is `ip`.
+  players:
+    type: array
+    description: >
+      Players that have used the target IP address. For player results, this
+      excludes the player in `player`.
+    items:
+      $ref: "../../openapi.yaml#/components/schemas/SeenPlayerSummary"

openapi/openapi.yaml

@@ -59,6 +59,8 @@ paths:
     $ref: "./paths/players/players-by-id-friends-by-id.yaml"
   /punishments:
     $ref: "./paths/punishments/punishments.yaml"
+  /punishments/seen:
+    $ref: "./paths/punishments/punishments-seen-by-target.yaml"
   /punishments/{punishmentId}:
     $ref: "./paths/punishments/punishments-by-id.yaml"
   /punishments/{punishmentId}/proofs:
@@ -166,6 +168,12 @@ components:
       $ref: "./components/schemas/punishment-updated-event.yaml"
     Revocation:
       $ref: "./components/schemas/revocation.yaml"
+    SeenPlayer:
+      $ref: "./components/schemas/seen-player.yaml"
+    SeenPlayerSummary:
+      $ref: "./components/schemas/seen-player-summary.yaml"
+    SeenResult:
+      $ref: "./components/schemas/seen-result.yaml"
     StreamEvent:
       $ref: "./components/schemas/stream-event.yaml"
       discriminator:

openapi/paths/punishments/punishments-seen-by-target.yaml

@@ -0,0 +1,48 @@
+get:
+  operationId: getPunishmentSeen
+  summary: Look up player activity
+  description: >
+    Returns the activity information shown by SpicyAzisaBan's `/seen` command.
+    The target may be a player UUID, an exact player name, or an IP address.
+    An IP-address lookup returns every player that has used that address; a
+    player lookup includes accounts that have used that player's current IP
+    address.
+  tags:
+    - punishments
+  security:
+    - apiKeyAuth:
+        - punishments:seen
+  parameters:
+    - name: target
+      in: query
+      required: true
+      description: The player UUID, player name, or IP address to look up.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 255
+    - name: ambiguous
+      in: query
+      description: Whether to match the target against any part of a player name.
+      schema:
+        type: boolean
+        default: false
+    - name: includeDummy
+      in: query
+      description: Whether to include placeholder records without any login timestamps.
+      schema:
+        type: boolean
+        default: false
+  responses:
+    "200":
+      description: The activity information was retrieved successfully.
+      content:
+        application/json:
+          schema:
+            $ref: "../../openapi.yaml#/components/schemas/SeenResult"
+    "401":
+      $ref: "../../openapi.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../../openapi.yaml#/components/responses/Forbidden"
+    "404":
+      description: No matching player or IP-address history was found.