openapi: 3.0.3
info:
  title: PyraLogs API
  version: 1.0.0
  description: |
    API specification for the PyraLogs application.
    PyraLogs allows users to register, authenticate, manage namespaces,
    generate JWT tokens for agents, and submit logs via a webhook.
servers:
  - url: http://127.0.0.1:{port}
    description: Local development server
    variables:
      port:
        default: '6544'
  - url: https://logs.unturf.com
    description: Production server

paths:
  /:
    get:
      summary: Home Page
      description: Displays the home page with public namespaces and user namespaces.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string

  /auth/login:
    get:
      summary: Display Login Page
      description: Renders the login page where users can enter their email.
      responses:
        '200':
          description: Login page rendered
          content:
            text/html:
              schema:
                type: string
    post:
      summary: Process Login
      description: Sends a verification code to the user's email.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
              required:
                - email
      responses:
        '302':
          description: Redirects to the verification page
          headers:
            Location:
              description: URL of the verification page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., email missing)
        '500':
          description: Internal Server Error

  /auth/verify:
    get:
      summary: Display Verification Page
      description: Renders the verification page where users can enter their code.
      responses:
        '200':
          description: Verification page rendered
          content:
            text/html:
              schema:
                type: string
    post:
      summary: Verify User
      description: Verifies the user's code and logs them in.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
                - code
      responses:
        '302':
          description: Redirects to the home page upon successful verification
          headers:
            Location:
              description: URL of the home page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., invalid code)
        '500':
          description: Internal Server Error

  /auth/logout:
    post:
      summary: Logout User
      description: Logs out the current user.
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                csrf_token:
                  type: string
      responses:
        '302':
          description: Redirects to the home page
          headers:
            Location:
              description: URL of the home page
              schema:
                type: string
        '403':
          description: Unauthorized (user not logged in)

  /auth/profile:
    get:
      summary: Display User Profile
      description: Shows the user's profile, including owned namespaces.
      security:
        - sessionAuth: []
      responses:
        '200':
          description: Profile page rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Unauthorized (user not logged in)
    post:
      summary: Update User Profile
      description: Updates the user's profile settings.
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                enable_gravatar:
                  type: string
                  enum: ['on']
                new_username:
                  type: string
              required:
                - new_username
            encoding:
              enable_gravatar:
                contentType: text/plain
              new_username:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the profile page
          headers:
            Location:
              description: URL of the profile page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., username already in use)
        '403':
          description: Unauthorized (user not logged in or guest mode)

  /namespace/create:
    get:
      summary: Display Namespace Creation Page
      description: Renders the form to create a new namespace.
      security:
        - sessionAuth: []
      responses:
        '200':
          description: Namespace creation page rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Unauthorized (user not logged in)
    post:
      summary: Create Namespace
      description: Processes the namespace creation form.
      security:
        - sessionAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                is_public:
                  type: string
                  enum: ['on']
            encoding:
              name:
                contentType: text/plain
              is_public:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., namespace name already exists)
        '403':
          description: Unauthorized (user not logged in)

  /namespace/{namespace_short_id}/manage:
    get:
      summary: Manage Namespace
      description: Displays the namespace management page (owners only).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      responses:
        '200':
          description: Namespace management page rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace not found

  /namespace/{namespace_short_id}/update:
    post:
      summary: Update Namespace
      description: Updates namespace properties (owners only).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                is_public:
                  type: string
                  enum: ['on']
                  description: 'Checkbox value. Present if checked.'
            encoding:
              is_public:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace not found

  /namespace/{namespace_short_id}/invite:
    post:
      summary: Invite User to Namespace
      description: Invites a user to the namespace with a specified role (owners only).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum: ['owner', 'editor', 'reader']
              required:
                - email
                - role
            encoding:
              email:
                contentType: text/plain
              role:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., invalid role)
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace not found

  /namespace/{namespace_short_id}/remove_user:
    post:
      summary: Remove User from Namespace
      description: Removes a user from the namespace (owners only, cannot remove self).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                user_id:
                  type: string
              required:
                - user_id
            encoding:
              user_id:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., cannot remove self)
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace or user not found

  /namespace/{namespace_short_id}/change_member_role:
    post:
      summary: Change Member Role in Namespace
      description: Changes a member's role in the namespace (owners only, cannot change own role).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                role:
                  type: string
                  enum: ['owner', 'editor', 'reader']
              required:
                - user_id
                - role
            encoding:
              user_id:
                contentType: text/plain
              role:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., cannot change own role)
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace or user not found

  /namespace/{namespace_short_id}/generate_agent_jwt:
    post:
      summary: Generate Agent JWT
      description: Generates a JWT token for an agent (owners only).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                agent_name:
                  type: string
              required:
                - agent_name
            encoding:
              agent_name:
                contentType: text/plain
      responses:
        '200':
          description: Agent JWT generated and displayed
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Bad Request (e.g., agent name missing)
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace not found

  /namespace/{namespace_short_id}/revoke_agent:
    post:
      summary: Revoke Agent
      description: Revokes an agent's access by invalidating their JWT (owners only).
      security:
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
              required:
                - agent_id
            encoding:
              agent_id:
                contentType: text/plain
      responses:
        '302':
          description: Redirects to the namespace management page
          headers:
            Location:
              description: URL of the namespace management page
              schema:
                type: string
        '400':
          description: Bad Request (e.g., agent ID missing)
        '403':
          description: Forbidden (not owner or not logged in)
        '404':
          description: Namespace or agent not found

  /namespace/{namespace_short_id}/logs:
    get:
      summary: View Namespace Logs
      description: |
        Displays logs for the specified namespace.
        - **Public Namespaces:** Accessible to all users, including guests.
        - **Private Namespaces:** Requires authentication and at least 'reader' role.
      security:
        - {}          # Allows public access to this endpoint
        - sessionAuth: []
      parameters:
        - in: path
          name: namespace_short_id
          required: true
          schema:
            type: string
          description: The short ID of the namespace
        - in: query
          name: q
          schema:
            type: string
          description: Search query to filter logs
      responses:
        '200':
          description: Logs page rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Forbidden (user does not have access to private namespace)
        '404':
          description: Namespace not found

  /webhook:
    post:
      summary: Submit Log Entry
      description: Allows agents to submit log entries via JWT authentication.
      security:
        - agentAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The log message
                level:
                  type: string
                  description: Log level (e.g., INFO, ERROR)
                  default: INFO
                metadata:
                  type: object
                  description: Additional metadata for the log entry
              required:
                - message
      responses:
        '201':
          description: Log entry created
        '400':
          description: Bad Request (e.g., message missing)
        '401':
          description: Unauthorized (missing or invalid JWT)
        '404':
          description: Namespace or agent not found

components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie for authenticated users
    agentAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication for agents