OPENAPI.yaml

openapi: 3.1.0
info:
  title: CodeLedger GitHub Authentication & Sync API
  description: CodeLedger relies heavily on standard GraphQL/REST platform endpoints and GitHub's Git Data Tree API. Below is the simplified spec indicating how CodeLedger interacts with Cloudflare workers for OAuth.
  version: 1.0.0

# Servers: update these to match `CONSTANTS.URLS` in src/core/constants.js.
servers:
  - url: https://codeledger.vkrishna04.me/api
    description: Production Cloudflare OAuth Bridge (AUTH_WORKER)
  - url: https://codeledger.vkrishna04.me
    description: Project landing / public docs
  - url: http://localhost:8787
    description: Local development worker (use when running the auth worker locally)

paths:
  /app/installations:
    get:
      summary: List GitHub App installations
      description: Returns a list of installations for the GitHub App. Requires an App JWT (server-side authentication).
      security:
        - app_jwt: []
      responses:
        "200":
          description: A JSON array of installation objects.

  /app/installations/{id}/access_tokens:
    post:
      summary: Create an installation access token
      description: Creates an installation access token for a given installation id (App JWT required).
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      security:
        - app_jwt: []
      responses:
        "201":
          description: Installation access token created (JSON)

  /auth/{provider}:
    get:
      summary: Initiate OAuth Flow for provider
      description: >
        Redirects the user to the chosen provider's authorization screen.
        Supported providers: github, gitlab, bitbucket.
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, gitlab, bitbucket]
      responses:
        "302":
          description: Redirection to provider authorization URL

  /auth/{provider}/callback:
    get:
      summary: OAuth Callback Receiver for provider
      description: >
        Exchanges the temporary authorization code for an access token, then
        communicates it back to the extension using window.postMessage on the
        opened window.
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
            enum: [github, gitlab, bitbucket]
        - in: query
          name: code
          required: true
          schema:
            type: string
      responses:
        "200":
          description: HTML page which posts the token back to the opener window.
          content:
            text/html:
              schema:
                type: string

  /webhook/github:
    post:
      summary: GitHub Webhook receiver
      description: >
        Verifies the x-hub-signature-256 HMAC signature of the request body
        and then processes webhook events.
      parameters:
        - in: header
          name: x-hub-signature-256
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json: {}
      responses:
        "200":
          description: Webhook processed

components:
  securitySchemes:
    githubToken:
      type: http
      scheme: bearer
      bearerFormat: GitHub OAuth
    app_jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT

x-extension-urls:
  description: >
    Browser extension internal URL params (library.html page, not HTTP endpoints).
    All params use window.history.replaceState — no page reload occurs on change.
  base: chrome-extension://{ext-id}/library/library.html
  params:
    tab:
      values: [solutions, analytics, graph, ai-chats, canonical, settings, search]
      description: Active top-level view
    settingsTab:
      values: [general, ai, git, platforms, backups, advanced]
      description: Active settings panel tab (only when tab=settings)
    problem:
      format: "{platformCode}-{titleSlug}"
      example: "lc-two-sum"
      description: Open ProblemModal for this problem id
    q:
      description: Search query (solutions view)
    difficulty:
      values: [Easy, Medium, Hard]
      description: Difficulty filter (solutions view)
    platform:
      values: [leetcode, geeksforgeeks, codeforces]
      description: Platform filter (solutions view)
    language:
      description: Language filter, matches lang.name (solutions view)
    sort:
      values: [newest, oldest, diff-asc, diff-desc, title, platform, tags]
      description: Sort order (solutions view)
    tag:
      description: Tag/topic filter (solutions view)
    section:
      values: [difficulty, language, platform, topic]
      description: Open analytics drill-down panel (only when tab=analytics)
    sectionFilter:
      description: Value for the section filter, e.g. "Python" or "Hard"
    graphLayout:
      values: [layered, circular, force]
      description: Graph layout mode (only when tab=graph)
  examples:
    - url: "library.html?tab=settings&settingsTab=git"
      description: Open settings directly on the Git tab
    - url: "library.html?tab=solutions&difficulty=Hard&platform=leetcode"
      description: Solutions filtered to hard LeetCode problems
    - url: "library.html?tab=solutions&problem=lc-two-sum"
      description: Open Two Sum modal (LeetCode)
    - url: "library.html?tab=analytics&section=language&sectionFilter=Python"
      description: Analytics with Python drill-down panel open
    - url: "library.html?tab=graph&graphLayout=force&problem=lc-two-sum"
      description: Graph in force layout with Two Sum modal open