openapi: 3.1.0
info:
  title: ReformCode API
  description: |
    AI-Powered Code Intelligence Platform API.

    ## Authentication
    All authenticated endpoints require a Bearer token obtained from Clerk.
    Include the token in the `Authorization` header:
    ```
    Authorization: Bearer <your_token>
    ```

    ## Rate Limiting
    Rate limits are tier-based:
    | Tier | Analysis/hr | Transform/hr |
    |------|-------------|--------------|
    | FREE | 30 | 20 |
    | PRO | 90 | 60 |
    | TEAM | 300 | 200 |

    Rate limit headers are included in all responses:
    - `X-RateLimit-Limit`: Maximum requests allowed
    - `X-RateLimit-Remaining`: Requests remaining
    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    ## Credits
    AI operations consume credits:
    | Operation | Credits |
    |-----------|---------|
    | Code Analysis | 1-3 |
    | Code Transform | 2-5 |
    | Repo Analysis | 2-5 |

    ## Versioning
    API version is included in the URL path (e.g., `/api/v1/`).
    The `X-API-Version` header indicates the version used.

  version: 1.0.0
  contact:
    name: ReformCode Support
    email: support@reformcode.com
    url: https://reformcode.com/docs
  license:
    name: Proprietary
    url: https://reformcode.com/terms
  x-logo:
    url: https://reformcode.com/logo.svg

servers:
  - url: https://reformcode.com/api/v1
    description: Production
  - url: https://staging.reformcode.com/api/v1
    description: Staging
  - url: http://localhost:3000/api/v1
    description: Local Development

tags:
  - name: Health
    description: Health check endpoints
  - name: Search
    description: Universal search across registries
  - name: Analysis
    description: AI-powered code analysis
  - name: Transform
    description: AI-powered code transformation
  - name: User
    description: User account and credits

paths:
  /health:
    get:
      tags: [Health]
      summary: Health Check
      description: Returns the health status of the API and its dependencies.
      operationId: getHealth
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /search:
    get:
      tags: [Search]
      summary: Universal Search
      description: Search across GitHub, NPM, and Docker Hub simultaneously.
      operationId: universalSearch
      parameters:
        - name: q
          in: query
          required: true
          description: Search query (1-200 characters)
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: sources
          in: query
          required: false
          description: Comma-separated list of sources to search
          schema:
            type: string
            default: github,npm,docker
            enum: [github, npm, docker, github,npm, github,docker, npm,docker, github,npm,docker]
        - name: limit
          in: query
          required: false
          description: Maximum results per source (1-50)
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /analyze/stream:
    post:
      tags: [Analysis]
      summary: Analyze Code (Streaming)
      description: |
        Analyze code using AI and stream the response.
        Returns Server-Sent Events (SSE) with analysis results.
      operationId: analyzeCodeStream
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeRequest'
      responses:
        '200':
          description: Streaming analysis response
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /transform/stream:
    post:
      tags: [Transform]
      summary: Transform Code (Streaming)
      description: |
        Transform code using AI and stream the response.
        Supports refactoring, conversion, and optimization.
      operationId: transformCodeStream
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransformRequest'
      responses:
        '200':
          description: Streaming transformation response
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Clerk JWT token

  schemas:
    HealthResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: string
              enum: [healthy, degraded, unhealthy]
            version:
              type: string
            timestamp:
              type: string
              format: date-time
            uptime:
              type: integer
              description: Uptime in seconds
            checks:
              type: object
              properties:
                database:
                  type: string
                  enum: [ok, error]
                redis:
                  type: string
                  enum: [ok, error, not_configured]
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    SearchResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            query:
              type: string
            results:
              type: object
              properties:
                github:
                  type: array
                  items:
                    $ref: '#/components/schemas/SearchResult'
                npm:
                  type: array
                  items:
                    $ref: '#/components/schemas/SearchResult'
                docker:
                  type: array
                  items:
                    $ref: '#/components/schemas/SearchResult'
            sources:
              type: array
              items:
                type: string
            totalResults:
              type: integer
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    SearchResult:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        source:
          type: string
          enum: [github, npm, docker]
        stars:
          type: integer
        downloads:
          type: integer

    AnalyzeRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: Code to analyze
          maxLength: 100000
        language:
          type: string
          description: Programming language
        prompt:
          type: string
          description: Custom analysis prompt
          maxLength: 1000
        model:
          type: string
          enum: [flash, pro]
          default: flash
          description: AI model to use (pro costs more credits)

    TransformRequest:
      type: object
      required:
        - code
        - transformation
      properties:
        code:
          type: string
          description: Code to transform
          maxLength: 100000
        transformation:
          type: string
          description: Type of transformation
          enum: [refactor, convert, optimize, modernize, document]
        targetLanguage:
          type: string
          description: Target language for conversion
        options:
          type: object
          description: Additional transformation options

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
        meta:
          $ref: '#/components/schemas/ResponseMeta'

    ResponseMeta:
      type: object
      properties:
        version:
          type: string
          description: API version
        timestamp:
          type: string
          format: date-time