{
  "openapi": "3.0.3",
  "info": {
    "title": "HiScores API",
    "description": "Static JSON API for contributor leaderboards and AI-generated project summaries.",
    "version": "1.0.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://{domain}",
      "description": "Your deployment URL",
      "variables": {
        "domain": {
          "default": "elizaos.github.io",
          "description": "Your GitHub Pages domain or custom domain"
        }
      }
    }
  ],
  "paths": {
    "/api/leaderboard-monthly.json": {
      "get": {
        "summary": "Monthly Leaderboard",
        "description": "Current month's contributor rankings",
        "operationId": "getMonthlyLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard-weekly.json": {
      "get": {
        "summary": "Weekly Leaderboard",
        "description": "Current week's contributor rankings",
        "operationId": "getWeeklyLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard-lifetime.json": {
      "get": {
        "summary": "Lifetime Leaderboard",
        "description": "All-time contributor rankings",
        "operationId": "getLifetimeLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/latest.json": {
      "get": {
        "summary": "Latest Overall Summary",
        "description": "Most recent overall project summary",
        "operationId": "getLatestOverallSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/index.json": {
      "get": {
        "summary": "Overall Summary Index",
        "description": "Index of all available overall summaries",
        "operationId": "getOverallSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/{date}.json": {
      "get": {
        "summary": "Overall Summary by Date",
        "description": "Overall project summary for a specific date",
        "operationId": "getOverallSummaryByDate",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          },
          {
            "$ref": "#/components/parameters/date"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/repos/{repoId}/{interval}/latest.json": {
      "get": {
        "summary": "Latest Repository Summary",
        "description": "Most recent summary for a specific repository",
        "operationId": "getLatestRepoSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/repoId"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/repos/{repoId}/{interval}/index.json": {
      "get": {
        "summary": "Repository Summary Index",
        "description": "Index of all available summaries for a repository",
        "operationId": "getRepoSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/repoId"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/contributors/{username}/{interval}/latest.json": {
      "get": {
        "summary": "Latest Contributor Summary",
        "description": "Most recent summary for a specific contributor",
        "operationId": "getLatestContributorSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/contributors/{username}/{interval}/index.json": {
      "get": {
        "summary": "Contributor Summary Index",
        "description": "Index of all available summaries for a contributor",
        "operationId": "getContributorSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contributors/{username}/profile.json": {
      "get": {
        "summary": "Contributor Profile",
        "description": "Complete character sheet with tier, class, rankings across all periods, and focus areas for a specific contributor",
        "operationId": "getContributorProfile",
        "tags": ["Profiles"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserProfileResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "interval": {
        "name": "interval",
        "in": "path",
        "required": true,
        "description": "Time interval for the summary",
        "schema": {
          "type": "string",
          "enum": ["day", "week", "month"]
        }
      },
      "date": {
        "name": "date",
        "in": "path",
        "required": true,
        "description": "Date in YYYY-MM-DD format",
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-01-15"
        }
      },
      "repoId": {
        "name": "repoId",
        "in": "path",
        "required": true,
        "description": "Repository identifier in owner_repo format",
        "schema": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9-]+_[a-zA-Z0-9-_.]+$",
          "example": "elizaos_eliza"
        }
      },
      "username": {
        "name": "username",
        "in": "path",
        "required": true,
        "description": "GitHub username",
        "schema": {
          "type": "string",
          "example": "wtfsayo"
        }
      }
    },
    "schemas": {
      "LeaderboardResponse": {
        "type": "object",
        "required": ["version", "period", "generatedAt", "totalUsers", "leaderboard"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "period": {
            "type": "string",
            "enum": ["monthly", "weekly", "lifetime"]
          },
          "startDate": {
            "type": "string",
            "format": "date",
            "example": "2025-01-01"
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "example": "2025-01-31"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "totalUsers": {
            "type": "integer",
            "example": 150
          },
          "leaderboard": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardEntry"
            }
          }
        }
      },
      "LeaderboardEntry": {
        "type": "object",
        "required": ["rank", "username", "score"],
        "properties": {
          "rank": {
            "type": "integer",
            "example": 1
          },
          "username": {
            "type": "string",
            "example": "contributor1"
          },
          "avatarUrl": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number",
            "example": 1250
          },
          "prScore": {
            "type": "number",
            "example": 800
          },
          "issueScore": {
            "type": "number",
            "example": 200
          },
          "reviewScore": {
            "type": "number",
            "example": 150
          },
          "commentScore": {
            "type": "number",
            "example": 100
          },
          "wallets": {
            "type": "object",
            "properties": {
              "solana": {
                "type": "string"
              },
              "ethereum": {
                "type": "string"
              }
            }
          }
        }
      },
      "SummaryResponse": {
        "type": "object",
        "required": ["version", "type", "interval", "date", "generatedAt", "content"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "type": {
            "type": "string",
            "enum": ["overall", "repository", "contributor"]
          },
          "interval": {
            "type": "string",
            "enum": ["day", "week", "month"]
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2025-01-15"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceLastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "contentHash": {
            "type": "string",
            "description": "SHA-256 hash of the content for cache validation"
          },
          "content": {
            "type": "string",
            "description": "Markdown-formatted summary content"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "entityId": {
                "type": "string"
              },
              "repoId": {
                "type": "string"
              },
              "owner": {
                "type": "string"
              },
              "repo": {
                "type": "string"
              },
              "username": {
                "type": "string"
              }
            }
          }
        }
      },
      "SummaryIndexResponse": {
        "type": "object",
        "required": ["version", "type", "interval", "generatedAt", "items"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "type": {
            "type": "string"
          },
          "interval": {
            "type": "string",
            "enum": ["day", "week", "month"]
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SummaryIndexItem"
            }
          }
        }
      },
      "SummaryIndexItem": {
        "type": "object",
        "required": ["date", "path"],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "sourceLastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "contentHash": {
            "type": "string"
          },
          "path": {
            "type": "string",
            "description": "Relative path to the summary file"
          }
        }
      },
      "UserProfileResponse": {
        "type": "object",
        "required": ["version", "username", "generatedAt", "characterSheet", "links"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "username": {
            "type": "string",
            "example": "contributor1"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "characterSheet": {
            "type": "object",
            "required": ["tier", "characterClass", "percentile", "rank", "scoreBreakdown", "focusAreas", "wallets"],
            "properties": {
              "tier": {
                "type": "string",
                "enum": ["beginner", "regular", "active", "veteran", "elite", "legend"],
                "example": "elite"
              },
              "characterClass": {
                "type": "string",
                "description": "Derived class (Author, Reviewer, Maintainer, etc.)",
                "example": "Maintainer"
              },
              "percentile": {
                "type": "number",
                "description": "Percentile ranking among all contributors",
                "example": 95.3
              },
              "rank": {
                "type": "object",
                "required": ["monthly", "weekly", "lifetime"],
                "properties": {
                  "monthly": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Rank in current month (null if no activity)",
                    "example": 12
                  },
                  "weekly": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Rank in current week (null if no activity)",
                    "example": 8
                  },
                  "lifetime": {
                    "type": "integer",
                    "nullable": true,
                    "description": "All-time rank (null if no activity)",
                    "example": 15
                  }
                }
              },
              "scoreBreakdown": {
                "$ref": "#/components/schemas/LeaderboardEntry/properties/scoreBreakdown"
              },
              "focusAreas": {
                "type": "array",
                "description": "Top expertise areas with rankings",
                "items": {
                  "$ref": "#/components/schemas/LeaderboardEntry/properties/focusAreas/items"
                }
              },
              "achievements": {
                "type": "array",
                "description": "Earned badges and achievements",
                "items": {
                  "$ref": "#/components/schemas/LeaderboardEntry/properties/achievements/items"
                }
              },
              "profile": {
                "$ref": "#/components/schemas/LeaderboardEntry/properties/profile"
              },
              "wallets": {
                "$ref": "#/components/schemas/LeaderboardEntry/properties/wallets"
              }
            }
          },
          "links": {
            "type": "object",
            "required": ["summaries", "github", "profile"],
            "properties": {
              "summaries": {
                "type": "object",
                "required": ["lifetime", "monthly", "weekly", "daily"],
                "properties": {
                  "lifetime": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/lifetime.json"
                  },
                  "monthly": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/month/latest.json"
                  },
                  "weekly": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/week/latest.json"
                  },
                  "daily": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/day/latest.json"
                  }
                }
              },
              "github": {
                "type": "string",
                "format": "uri",
                "example": "https://github.com/contributor1"
              },
              "profile": {
                "type": "string",
                "format": "uri",
                "example": "https://elizaos.github.io/profile/contributor1"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Leaderboard",
      "description": "Contributor ranking endpoints"
    },
    {
      "name": "Profiles",
      "description": "Individual contributor character sheets"
    },
    {
      "name": "Summaries",
      "description": "AI-generated project summaries"
    }
  ]
}