openapi: "3.0.0"
info:
  title: "Live Global Leaderboard API"
  description: "API for placing entries on and reading from the global pay-to-rank leaderboard"
  version: "1.0.0"
servers:
  - url: "https://YOUR_PROJECT_REF.supabase.co/functions/v1"
    description: "Supabase Edge Functions (replace YOUR_PROJECT_REF with your project reference)"
paths:
  /create-checkout:
    post:
      summary: "Create a payment session to rank on the leaderboard"
      description: "Returns a checkout URL. Complete the payment at the returned URL to appear on the leaderboard. Payment completion requires browser interaction."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, amount_cents]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 10
                  description: "Display name on leaderboard"
                amount_cents:
                  type: integer
                  minimum: 100
                  description: "Payment amount in cents (100 = $1.00 USD)"
                country_code:
                  type: string
                  description: "ISO 3166-1 alpha-2 country code"
                country:
                  type: string
                  description: "Country name"
                flag:
                  type: string
                  description: "Flag emoji"
                message:
                  type: string
                  maxLength: 55
                  description: "Custom message (max 10 words)"
                link:
                  type: string
                  maxLength: 100
                  description: "URL to attach to profile (must start with https://)"
                provider:
                  type: string
                  enum: [stripe, coinbase]
                  default: stripe
                  description: "Payment provider"
      responses:
        "200":
          description: "Checkout session created"
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "Redirect URL to complete payment"
                  id:
                    type: string
                    description: "Session ID"
        "400":
          description: "Validation error"
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: "Error message"
        "405":
          description: "Method not allowed (non-POST request)"
  /leaderboard-api:
    get:
      summary: "Read current leaderboard rankings"
      description: "Returns the current leaderboard as a JSON array of ranked players. Players are aggregated by name with total amounts summed. Public endpoint, no authentication required."
      parameters:
        - name: timeframe
          in: query
          required: false
          schema:
            type: string
            enum: [daily, weekly, monthly, yearly, alltime]
            default: alltime
          description: "Leaderboard timeframe filter"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: "Maximum number of ranked players to return"
      responses:
        "200":
          description: "Ranked leaderboard data"
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeframe:
                    type: string
                    description: "Active timeframe filter"
                  count:
                    type: integer
                    description: "Number of players returned"
                  players:
                    type: array
                    items:
                      type: object
                      properties:
                        rank:
                          type: integer
                        name:
                          type: string
                        flag:
                          type: string
                        country:
                          type: string
                        message:
                          type: string
                        total_cents:
                          type: integer
                          description: "Total amount paid in cents"
                        total_usd:
                          type: string
                          description: "Total amount formatted as USD string"
                        latest_payment:
                          type: string
                          format: date-time
                          description: "ISO 8601 timestamp of most recent payment"