Add POST /player/basic/batch (#147)

owens1127 · cursoragent · web-flow · commit 20fd56ef51bc · 2026-06-16T22:49:23.000-04:00
* Add POST /player/basic/batch for multi-player name resolution.

Single round-trip for up to 12 membership IDs using WHERE membership_id = ANY(...). Used by Website fireteam display to avoid N+1 basic calls.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

* Fix basic-batch test typing and regenerate OpenAPI spec.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

* Compare membershipId as bigint in basic-batch test.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;

---------

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/open-api/openapi.json b/open-api/openapi.json
@@ -2428,6 +2428,18 @@
         "required": ["params", "results"],
         "additionalProperties": false
       },
+      "PlayerBasicBatchResponse": {
+        "type": "object",
+        "properties": {
+          "players": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PlayerInfo"
+            }
+          }
+        },
+        "required": ["players"]
+      },
       "PlayerHistoryResponse": {
         "type": "object",
         "properties": {
@@ -4169,6 +4181,144 @@
         }
       }
     },
+    "/player/basic/batch": {
+      "post": {
+        "description": "Batch variant of `/player/{membershipId}/basic`. Resolves up to 12 players in one round-trip.",
+        "summary": "/player/basic/batch",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "membershipIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "pattern": "^\\d+n?$"
+                    },
+                    "minItems": 1,
+                    "maxItems": 12
+                  }
+                },
+                "required": ["membershipIds"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "minted": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "success": {
+                      "type": "boolean",
+                      "enum": [true]
+                    },
+                    "response": {
+                      "$ref": "#/components/schemas/PlayerBasicBatchResponse"
+                    }
+                  },
+                  "required": ["minted", "success", "response"]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "minted": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "success": {
+                      "type": "boolean",
+                      "enum": [false]
+                    },
+                    "code": {
+                      "type": "string",
+                      "enum": ["BodyValidationError"]
+                    },
+                    "error": {
+                      "$ref": "#/components/schemas/BodyValidationError"
+                    }
+                  },
+                  "required": ["minted", "success", "code", "error"]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "minted": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "success": {
+                      "type": "boolean",
+                      "enum": [false]
+                    },
+                    "code": {
+                      "type": "string",
+                      "enum": ["ApiKeyError"]
+                    },
+                    "error": {
+                      "$ref": "#/components/schemas/ApiKeyError"
+                    }
+                  },
+                  "required": ["minted", "success", "code", "error"]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "minted": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "success": {
+                      "type": "boolean",
+                      "enum": [false]
+                    },
+                    "code": {
+                      "type": "string",
+                      "enum": ["InternalServerError"]
+                    },
+                    "error": {
+                      "$ref": "#/components/schemas/InternalServerError"
+                    }
+                  },
+                  "required": ["minted", "success", "code", "error"]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/player/{membershipId}/history": {
       "get": {
         "description": "/activities is deprecated. Use /history now. Get a player's activity history. This endpoint uses date cursors to paginate through a player's activity history. \nThe first request should not include a cursor. Subsequent requests should include the `nextCursor` \nvalue from the previous response. Note that the first request may not return the full number of activities requested\nin order to optimize performance. Subsequent requests will return the full number of activities requested.",
diff --git a/src/routes/player/basic-batch.test.ts b/src/routes/player/basic-batch.test.ts
@@ -0,0 +1,53 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+
+import { getFixturePool } from "@/lib/test-fixture-db"
+import { expectOk } from "@/lib/test-utils"
+
+import { playerBasicBatchRoute } from "./basic-batch"
+
+const fixtureDb = getFixturePool()
+const fixtureMembershipId = "4611686019000000402"
+
+beforeAll(async () => {
+    await fixtureDb.query(`DELETE FROM core.player_stats WHERE membership_id = $1::bigint`, [
+        fixtureMembershipId
+    ])
+    await fixtureDb.query(`DELETE FROM core.player WHERE membership_id = $1::bigint`, [
+        fixtureMembershipId
+    ])
+    await fixtureDb.query(
+        `INSERT INTO core.player (
+            membership_id, membership_type, icon_path, display_name,
+            bungie_global_display_name, bungie_global_display_name_code, last_seen, first_seen,
+            clears, fresh_clears, sherpas, total_time_played_seconds, sum_of_best, wfr_score,
+            cheat_level, is_private, is_whitelisted, updated_at
+        ) VALUES
+        ($1::bigint, 3, NULL, 'fixture_basic_batch', 'fixture_basic_batch', '0402', NOW(), NOW(), 1, 1, 0, 100, 100, 0, 0, false, false, NOW())`,
+        [fixtureMembershipId]
+    )
+})
+
+afterAll(async () => {
+    await fixtureDb.query(`DELETE FROM core.player_stats WHERE membership_id = $1::bigint`, [
+        fixtureMembershipId
+    ])
+    await fixtureDb.query(`DELETE FROM core.player WHERE membership_id = $1::bigint`, [
+        fixtureMembershipId
+    ])
+})
+
+describe("player basic batch 200", () => {
+    test("returns found players and omits unknown ids", async () => {
+        const result = await playerBasicBatchRoute.$mock({
+            body: {
+                membershipIds: [fixtureMembershipId, "1"]
+            }
+        })
+
+        expectOk(result)
+        if (result.type === "ok") {
+            expect(result.parsed.players).toHaveLength(1)
+            expect(result.parsed.players[0]?.membershipId).toBe(BigInt(fixtureMembershipId))
+        }
+    })
+})
diff --git a/src/routes/player/basic-batch.ts b/src/routes/player/basic-batch.ts
@@ -0,0 +1,35 @@
+import { RaidHubRoute } from "@/core/RaidHubRoute"
+import { playersQueue } from "@/integrations/rabbitmq/queues"
+import { cacheControl } from "@/middleware/cache-control"
+import { zPlayerInfo } from "@/schema/components/PlayerInfo"
+import { zBigIntString } from "@/schema/input"
+import { getPlayers } from "@/services/player"
+import { z } from "zod"
+
+export const playerBasicBatchRoute = new RaidHubRoute({
+    method: "post",
+    description:
+        "Batch variant of `/player/{membershipId}/basic`. Resolves up to 12 players in one round-trip.",
+    body: z.object({
+        membershipIds: z.array(zBigIntString()).min(1).max(12)
+    }),
+    middleware: [cacheControl(300)],
+    response: {
+        success: {
+            statusCode: 200,
+            schema: z.object({
+                players: z.array(zPlayerInfo)
+            })
+        },
+        errors: []
+    },
+    async handler(req, after) {
+        const players = await getPlayers(req.body.membershipIds)
+
+        after(async () => {
+            await Promise.all(req.body.membershipIds.map(id => playersQueue.send(id)))
+        })
+
+        return RaidHubRoute.ok({ players })
+    }
+})
diff --git a/src/routes/player/index.ts b/src/routes/player/index.ts
@@ -1,4 +1,5 @@
 import { RaidHubRouter } from "@/core/RaidHubRouter"
+import { playerBasicBatchRoute } from "./basic-batch"
 import { playerBasicRoute } from "./membershipId/basic"
 import { playerHistoryRoute } from "./membershipId/history"
 import { playerInstancesRoute } from "./membershipId/instances"
@@ -9,6 +10,7 @@ import { playerSearchRoute } from "./search"
 export const playerRouter = new RaidHubRouter({
     routes: [
         { path: "/search", route: playerSearchRoute },
+        { path: "/basic/batch", route: playerBasicBatchRoute },
         {
             path: "/:membershipId",
             route: new RaidHubRouter({
diff --git a/src/services/player.ts b/src/services/player.ts
@@ -26,6 +26,28 @@ export const getPlayer = async (membershipId: bigint | string) => {
         { params: [membershipId] }
     )
 }
+
+export const getPlayers = async (membershipIds: readonly (bigint | string)[]) => {
+    if (!membershipIds.length) {
+        return []
+    }
+
+    return await pgReader.queryRows<PlayerInfo>(
+        `SELECT
+            membership_id AS "membershipId",
+            membership_type AS "membershipType",
+            icon_path AS "iconPath",
+            display_name AS "displayName",
+            bungie_global_display_name AS "bungieGlobalDisplayName",
+            bungie_global_display_name_code AS "bungieGlobalDisplayNameCode",
+            last_seen AS "lastSeen",
+            is_private AS "isPrivate",
+            cheat_level AS "cheatLevel"
+        FROM player
+        WHERE membership_id = ANY($1::bigint[])`,
+        { params: [membershipIds] }
+    )
+}
 export const getPlayerActivityStats = async (membershipId: bigint | string) => {
     return await withHistogramTimer(
         playerProfileQueryTimer,
