Merge pull request #47 from superfluid-org/claude/add-campaign-accounts-endpoint-siYhG

kasparkallas · web-flow · commit 9e0f64699374 · 2026-03-03T20:38:32.000+02:00
Add campaign accounts leaderboard endpoint
diff --git a/cms/src/app/(api)/points/accounts/route.ts b/cms/src/app/(api)/points/accounts/route.ts
@@ -0,0 +1,132 @@
+import type { CampaignAccountsResponse } from "@/domains/points/types"
+import { getPayloadInstance } from "@/payload"
+
+const VALID_ORDER_BY = ["totalPoints", "eventCount", "lastEventAt"] as const
+
+/**
+ * GET /points/accounts?campaignId=42
+ * Query all accounts in a campaign with their point balances.
+ * Supports sorting and pagination for leaderboard display.
+ *
+ * Query params:
+ * - campaignId (required): Campaign ID
+ * - orderBy (optional): totalPoints | eventCount | lastEventAt (default: totalPoints)
+ * - order (optional): asc | desc (default: desc)
+ * - limit (optional): 1-100 (default: 50)
+ * - page (optional): positive integer (default: 1)
+ */
+export const GET = async (request: Request): Promise<Response> => {
+	try {
+		const url = new URL(request.url)
+
+		// Get campaignId parameter (required, must be numeric)
+		const campaignIdParam = url.searchParams.get("campaignId")
+		if (!campaignIdParam) {
+			return Response.json({ message: "Missing required query parameter: campaignId" }, { status: 400 })
+		}
+
+		const campaignId = parseInt(campaignIdParam, 10)
+		if (Number.isNaN(campaignId) || campaignId <= 0) {
+			return Response.json({ message: "campaignId must be a positive integer" }, { status: 400 })
+		}
+
+		// Parse and validate orderBy
+		const orderByParam = url.searchParams.get("orderBy")
+		let orderBy: (typeof VALID_ORDER_BY)[number] = "totalPoints"
+		if (orderByParam) {
+			if (!VALID_ORDER_BY.includes(orderByParam as (typeof VALID_ORDER_BY)[number])) {
+				return Response.json(
+					{ message: `orderBy must be one of: ${VALID_ORDER_BY.join(", ")}` },
+					{ status: 400 },
+				)
+			}
+			orderBy = orderByParam as (typeof VALID_ORDER_BY)[number]
+		}
+
+		// Parse and validate order
+		const orderParam = url.searchParams.get("order")
+		let order: "asc" | "desc" = "desc"
+		if (orderParam) {
+			if (orderParam !== "asc" && orderParam !== "desc") {
+				return Response.json({ message: "order must be 'asc' or 'desc'" }, { status: 400 })
+			}
+			order = orderParam
+		}
+
+		// Parse and validate limit
+		const limitParam = url.searchParams.get("limit")
+		let limit = 50
+		if (limitParam) {
+			const parsed = Number.parseInt(limitParam, 10)
+			if (Number.isNaN(parsed) || parsed < 1 || parsed > 100) {
+				return Response.json({ message: "limit must be between 1 and 100" }, { status: 400 })
+			}
+			limit = parsed
+		}
+
+		// Parse and validate page
+		const pageParam = url.searchParams.get("page")
+		let page = 1
+		if (pageParam) {
+			const parsed = Number.parseInt(pageParam, 10)
+			if (Number.isNaN(parsed) || parsed < 1) {
+				return Response.json({ message: "page must be a positive integer" }, { status: 400 })
+			}
+			page = parsed
+		}
+
+		// Verify campaign exists
+		const payload = await getPayloadInstance()
+		const campaignResult = await payload.find({
+			collection: "campaigns",
+			where: { id: { equals: campaignId } },
+			limit: 1,
+		})
+
+		if (campaignResult.docs.length === 0) {
+			return Response.json({ message: "Campaign not found" }, { status: 404 })
+		}
+
+		// Build Payload sort string: prefix with "-" for descending
+		const sort = order === "desc" ? `-${orderBy}` : orderBy
+
+		// Query point balances for all accounts in the campaign
+		const result = await payload.find({
+			collection: "point-balances",
+			where: {
+				campaign: { equals: campaignId },
+			},
+			sort,
+			limit,
+			page,
+		})
+
+		const response: CampaignAccountsResponse = {
+			accounts: result.docs.map((doc) => ({
+				account: doc.account,
+				totalPoints: doc.totalPoints,
+				eventCount: doc.eventCount,
+				lastEventAt: doc.lastEventAt ?? null,
+			})),
+			pagination: {
+				page: result.page ?? 1,
+				limit: result.limit,
+				totalDocs: result.totalDocs,
+				totalPages: result.totalPages,
+				hasNextPage: result.hasNextPage,
+				hasPrevPage: result.hasPrevPage,
+			},
+		}
+
+		return Response.json(response)
+	} catch (error) {
+		console.error("Failed to query campaign accounts:", error)
+
+		return Response.json(
+			{
+				message: error instanceof Error ? error.message : "Failed to query campaign accounts",
+			},
+			{ status: 500 },
+		)
+	}
+}
diff --git a/cms/src/domains/points/api/registry.ts b/cms/src/domains/points/api/registry.ts
@@ -5,6 +5,9 @@ import {
 	BalanceBatchResponseSchema,
 	BalancePostBodySchema,
 	BalanceQuerySchema,
+	CampaignAccountSchema,
+	CampaignAccountsQuerySchema,
+	CampaignAccountsResponseSchema,
 	EventBalanceQuerySchema,
 	EventBalanceResponseSchema,
 	EventsQuerySchema,
@@ -34,6 +37,8 @@ pointsRegistry.register("SignedBalanceResponse", SignedBalanceResponseSchema)
 pointsRegistry.register("SignedBalanceBatchResponse", SignedBalanceBatchResponseSchema)
 pointsRegistry.register("BalanceBatchResponse", BalanceBatchResponseSchema)
 pointsRegistry.register("EventBalanceResponse", EventBalanceResponseSchema)
+pointsRegistry.register("CampaignAccount", CampaignAccountSchema)
+pointsRegistry.register("CampaignAccountsResponse", CampaignAccountsResponseSchema)
 pointsRegistry.register("ApiError", ApiErrorSchema)
 
 // Register security scheme
@@ -292,6 +297,79 @@ This endpoint queries the raw point events and aggregates on-demand, unlike \`/b
 	},
 })
 
+// ============================================
+// GET /points/accounts
+// ============================================
+pointsRegistry.registerPath({
+	method: "get",
+	path: "/points/accounts",
+	summary: "Get campaign accounts (leaderboard)",
+	description:
+		"Retrieves all accounts in a campaign with their point balances, event counts, and last event timestamps. Results are paginated and sortable, making this ideal for building leaderboard views.",
+	tags: ["Balance"],
+	request: {
+		query: CampaignAccountsQuerySchema,
+	},
+	responses: {
+		200: {
+			description: "Campaign accounts retrieved successfully",
+			content: {
+				"application/json": {
+					schema: CampaignAccountsResponseSchema,
+					example: {
+						accounts: [
+							{
+								account: "0x1234567890abcdef1234567890abcdef12345678",
+								totalPoints: 1500,
+								eventCount: 42,
+								lastEventAt: "2026-01-15T12:00:00.000Z",
+							},
+							{
+								account: "0xabcdef1234567890abcdef1234567890abcdef12",
+								totalPoints: 750,
+								eventCount: 18,
+								lastEventAt: "2026-01-14T08:30:00.000Z",
+							},
+						],
+						pagination: {
+							page: 1,
+							limit: 50,
+							totalDocs: 150,
+							totalPages: 3,
+							hasNextPage: true,
+							hasPrevPage: false,
+						},
+					},
+				},
+			},
+		},
+		400: {
+			description: "Invalid request (missing/invalid campaignId, invalid orderBy, or invalid pagination)",
+			content: {
+				"application/json": {
+					schema: ApiErrorSchema,
+				},
+			},
+		},
+		404: {
+			description: "Campaign not found",
+			content: {
+				"application/json": {
+					schema: ApiErrorSchema,
+				},
+			},
+		},
+		500: {
+			description: "Internal server error",
+			content: {
+				"application/json": {
+					schema: ApiErrorSchema,
+				},
+			},
+		},
+	},
+})
+
 // ============================================
 // GET /points/signed-balance
 // ============================================
@@ -789,7 +867,7 @@ npx @hey-api/openapi-ts -i https://cms.superfluid.pro/points/openapi.json \\
 
 ### Authentication
 
-**Query Endpoints** (\`/balance\`, \`/signed-balance\`, \`/events\`): Public access, no authentication required. Use numeric \`campaignId\` as query parameter.
+**Query Endpoints** (\`/balance\`, \`/signed-balance\`, \`/events\`, \`/accounts\`): Public access, no authentication required. Use numeric \`campaignId\` as query parameter.
 
 **Push Endpoint** (\`/push\`): Requires API key in the \`X-API-Key\` header. API keys are scoped to a specific campaign.
 
@@ -877,10 +955,17 @@ const { data: campaigns } = await client.POST('/points/balance-batch', {
   body: { campaignIds: [1, 2, 3], account: '0x1234...' }
 });
 // { address, campaignIds, points, warnings? }
+
+// Leaderboard - all accounts ranked by points (GET)
+const { data: leaderboard } = await client.GET('/points/accounts', {
+  params: { query: { campaignId: 42, orderBy: 'totalPoints', order: 'desc' } }
+});
+// { accounts: [{ account, totalPoints, eventCount, lastEventAt }], pagination }
 \`\`\`
 
 > **Note:** Stack.so only offered \`getSignedPointsBatch()\` for querying multiple campaigns (signed).
 > The unsigned \`/points/balance-batch\` endpoint is a new capability.
+> The \`/points/accounts\` endpoint is a new leaderboard capability with no Stack.so equivalent.
 
 ### Signed Points (On-Chain Verification)
 
diff --git a/cms/src/domains/points/api/schemas.ts b/cms/src/domains/points/api/schemas.ts
@@ -379,6 +379,74 @@ export const PushResponseSchema = z
 		description: "Response from push endpoint (202 Accepted)",
 	})
 
+// ============================================
+// Campaign Accounts Endpoint Schemas
+// ============================================
+
+export const CampaignAccountsQuerySchema = z
+	.object({
+		campaignId: z.coerce.number().int().positive().openapi({
+			example: 42,
+			description: "Campaign ID",
+		}),
+		orderBy: z.enum(["totalPoints", "eventCount", "lastEventAt"]).optional().openapi({
+			example: "totalPoints",
+			description: "Field to order results by (default: totalPoints)",
+		}),
+		order: z.enum(["asc", "desc"]).optional().openapi({
+			example: "desc",
+			description: "Sort order (default: desc)",
+		}),
+		limit: z.coerce.number().int().min(1).max(100).optional().openapi({
+			example: 50,
+			description: "Number of results per page (1-100, default: 50)",
+		}),
+		page: z.coerce.number().int().positive().optional().openapi({
+			example: 1,
+			description: "Page number (default: 1)",
+		}),
+	})
+	.openapi({
+		title: "CampaignAccountsQuery",
+		description: "Query parameters for campaign accounts (leaderboard) endpoint",
+	})
+
+export const CampaignAccountSchema = z
+	.object({
+		account: z.string().openapi({
+			example: "0x1234567890abcdef1234567890abcdef12345678",
+			description: "Ethereum wallet address",
+		}),
+		totalPoints: z.number().openapi({
+			example: 1500,
+			description: "Total accumulated points in the campaign",
+		}),
+		eventCount: z.number().openapi({
+			example: 42,
+			description: "Total number of point events for this account",
+		}),
+		lastEventAt: z.string().nullable().openapi({
+			example: "2026-01-15T12:00:00.000Z",
+			description: "ISO 8601 timestamp of the most recent event, or null if no events",
+		}),
+	})
+	.openapi({
+		title: "CampaignAccount",
+		description: "Account entry with point balance and metadata for a campaign",
+	})
+
+export const CampaignAccountsResponseSchema = z
+	.object({
+		accounts: z.array(CampaignAccountSchema).openapi({
+			description: "List of accounts with their point balances",
+		}),
+		pagination: PaginationSchema,
+	})
+	.openapi({
+		title: "CampaignAccountsResponse",
+		description: "Paginated list of campaign accounts for leaderboard display",
+	})
+
 // ============================================
 // Signed Balance Endpoint Schemas
 // ============================================
diff --git a/cms/src/domains/points/types.ts b/cms/src/domains/points/types.ts
@@ -88,3 +88,21 @@ export const eventBalanceResponseSchema = z.object({
 })
 
 export type EventBalanceResponse = z.infer<typeof eventBalanceResponseSchema>
+
+// Campaign account response (for leaderboard)
+export const campaignAccountResponseSchema = z.object({
+	account: z.string(),
+	totalPoints: z.number(),
+	eventCount: z.number(),
+	lastEventAt: z.string().nullable(),
+})
+
+export type CampaignAccountResponse = z.infer<typeof campaignAccountResponseSchema>
+
+// Campaign accounts list response
+export const campaignAccountsResponseSchema = z.object({
+	accounts: z.array(campaignAccountResponseSchema),
+	pagination: paginationSchema,
+})
+
+export type CampaignAccountsResponse = z.infer<typeof campaignAccountsResponseSchema>
