openapi: 3.0.3
info:
  title: Shoehorn Notifications API
  description: User notification management and preferences.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /notifications:
    get:
      summary: List notifications
      description: Returns notifications for the current user.
      tags: [Notifications]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: cursor
          in: query
          schema: { type: string }
        - name: unread
          in: query
          description: Filter to unread only
          schema: { type: boolean }
      responses:
        '200':
          description: User notifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  notifications:
                    type: array
                    items: { $ref: '#/components/schemas/Notification' }
                  unread_count: { type: integer }
                  pagination:
                    type: object
                    properties:
                      nextCursor: { type: string }

  /notifications/{id}/read:
    post:
      summary: Mark notification as read
      tags: [Notifications]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Notification marked as read

  /notifications/read-all:
    post:
      summary: Mark all notifications as read
      tags: [Notifications]
      responses:
        '200':
          description: All notifications marked as read

  /notifications/preferences:
    get:
      summary: Get notification preferences
      tags: [Notifications]
      responses:
        '200':
          description: User notification preferences
          content:
            application/json:
              schema: { $ref: '#/components/schemas/NotificationPreferences' }

    put:
      summary: Update notification preferences
      tags: [Notifications]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NotificationPreferences' }
      responses:
        '200':
          description: Preferences updated

components:
  schemas:
    Notification:
      type: object
      properties:
        id: { type: string, format: uuid }
        type: { type: string, enum: [info, warning, error, success] }
        title: { type: string }
        message: { type: string }
        url: { type: string, description: Deep link to related resource }
        entity_id: { type: string }
        read: { type: boolean }
        created_at: { type: string, format: date-time }

    NotificationPreferences:
      type: object
      properties:
        email_enabled: { type: boolean }
        governance_actions: { type: boolean }
        scorecard_changes: { type: boolean }
        deployment_events: { type: boolean }
        forge_run_updates: { type: boolean }
        security_findings: { type: boolean }
