Simple Leaderboard Function

This is a basic online leaderboard function made with Supabase. This code is mainly meant to be used with our project, Meltdown.

Usage

Use any API clients, or curl like the following:

curl -X POST <PUBLIC_URL>/functions/v1/leaderboard \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <LOCAL_ANON_KEY>" \
  -d '{"playerScore": 4200}' # payload body in JSON

Leaderboard API

Base URL: /functions/v1/leaderboard

All responses are JSON. All error responses follow the shape { "error": string }.

---

Endpoints

GET / — Get top N players

Returns the top players on the leaderboard, ranked by their best (highest) score.

Query Parameters

Parameter	Type	Required	Default	Constraints	Description
count	integer	No	5	Min: 1, Max: 50	Number of top players to return

Responses

Status	Description
200	Success
500	Internal server error

200 Response

{
  "count": 5,
  "top_players": [
    {
      "player_name": "Alice",
      "best_score": "98000"
    }
  ]
}

top_players entry shape

Field	Type	Description
player_name	string	Player's name
best_score	string	Player's all-time highest score (numeric string)

---

GET /?playerName= — Get scores for a player

Returns a list of score entries for a specific player, ordered newest first. Each entry includes the score's global rank across all leaderboard entries.

Query Parameters

Parameter	Type	Required	Default	Constraints	Description
playerName	string	Yes	—	Max: 64 chars	The player's name to look up
count	integer	No	5	Min: 1, Max: 50	Number of score entries to return

Responses

Status	Description
200	Success
404	Player not found
500	Internal server error

200 Response

{
  "player_name": "Alice",
  "count": 5,
  "total_entries": 3,
  "scores": [
    {
      "id": 12,
      "score": "98000",
      "rank": 1,
      "created_at": "2026-03-07T09:00:00Z"
    }
  ]
}

scores entry shape

Field	Type	Description
id	number	Unique score entry ID
score	string	Score value as a numeric string
rank	number	Global rank of this score across all players
created_at	string	ISO 8601 timestamp of when the score was recorded

---

POST /?playerName= — Submit a score

Inserts a new score entry for a player.

Query Parameters

Parameter	Type	Required	Constraints	Description
playerName	string	Yes	Max: 64 chars	The player's name

Request Body (application/json)

Field	Type	Required	Description
playerScore	number | string	Yes	The score to record. Use a number for values ≤ 9007199254740991. Use a numeric string for larger values to avoid precision loss.

{ "playerScore": 15000 }

{ "playerScore": "99999999999999999999" }

Responses

Status	Description
201	Score created successfully
400	Validation error
500	Internal server error

201 Response

{
  "data": {
    "id": 42,
    "player_name": "Alice",
    "score": "15000",
    "created_at": "2026-03-07T11:00:00Z"
  }
}

400 Error cases

Cause	Error message
playerName missing or empty	`playerName` is required and must be a non-empty string.
playerName too long	`playerName` must not exceed 64 characters.
playerScore missing or wrong type	`playerScore` is required and must be a number or numeric string.
playerScore is a float	`playerScore` must be an integer, not a float.
playerScore is a number above MAX_SAFE_INTEGER	`playerScore` exceeds Number.MAX_SAFE_INTEGER. Pass it as a numeric string instead.
playerScore is outside PostgreSQL bigint range	`playerScore` is outside the PostgreSQL bigint range.

---

PATCH /?playerName= — Rename a player

Renames a player across all their score entries.

Query Parameters

Parameter	Type	Required	Constraints	Description
playerName	string	Yes	Max: 64 chars	The player's current name

Request Body (application/json)

Field	Type	Required	Constraints	Description
newPlayerName	string	Yes	Max: 64 chars	The new name for the player

{ "newPlayerName": "Bob" }

Responses

Status	Description
200	Player successfully renamed
400	Validation error
404	Player not found
409	New name is already taken
500	Internal server error

200 Response

{
  "message": "Player \"Alice\" successfully renamed to \"Bob\".",
  "updated_entries": 3
}

400 Error cases

Cause	Error message
playerName missing or empty	`playerName` is required and must be a non-empty string.
Either name exceeds 64 characters	`playerName` must not exceed 64 characters.
Body is missing or not valid JSON	Request body is missing or is not valid JSON
newPlayerName missing or empty	`newPlayerName` is required and must be a non-empty string.
newPlayerName is the same as playerName	`newPlayerName` must be different from the current player name.

---

DELETE /?playerName= — Remove a player

Permanently deletes a player and all their score entries.

Query Parameters

Parameter	Type	Required	Constraints	Description
playerName	string	Yes	Max: 64 chars	The name of the player to remove

Responses

Status	Description
200	Player successfully removed
400	Validation error
404	Player not found
500	Internal server error

200 Response

{
  "message": "Player \"Alice\" and all their scores have been removed.",
  "deleted_entries": 3
}

400 Error cases

Cause	Error message
playerName missing or empty	`playerName` query param is required.
playerName too long	`playerName` must not exceed 64 characters.

---

Common error shapes

404 Not Found

{ "error": "Player \"Alice\" not found." }

409 Conflict (PATCH only)

{ "error": "Player name \"Bob\" is already taken." }

500 Internal Server Error

{ "error": "Unexpected error message" }

Supabase Project Commands

These are some commonly used commands for working with Supabase.

# login
supabase login

# db schema update
supabase db diff -f name_of_the_change

# start supabase project locally
supabase start

# list access keys
supabase secrets list

# clear all local db
supabase db reset

# apply the db migration locally
supabase migration up

# serve the edge functions locally with logs
supabase functions serve

# deploy the database to production
supabase db push